bosch_camera.py

#!/usr/bin/env python3
"""
Bosch Smart Home Camera — All-in-one Standalone Tool
Version: 7.0.0
=====================================================
No hardcoded camera IDs or credentials.
All configuration is stored in bosch_config.json (created on first run).

First run:
  1. Creates bosch_config.json with empty credentials
  2. Prompts for Bearer token (via mitmproxy — see README)
  3. Auto-discovers all cameras from the API
  4. Saves cameras + token to config file

Subsequent runs:
  • Reads cameras from config (no repeated discovery needed)
  • If token is expired → prompts for a fresh one → saves to config

Snapshot methods (newest → fastest, tried in order):
  1. Cloud proxy live snap  — proxy-NN.live.cbs.boschsecurity.com snap.jpg
                               (only if a live connection has been opened)
  2. Local camera snap      — https://<local_ip>/snap.jpg  (Digest auth)
                               (only if local_ip + credentials are set in config)
  3. Latest event snapshot  — most recent motion-triggered JPEG from cloud events API
                               (always available, but only updates on motion)

Usage (interactive menu):
  python3 bosch_camera.py

Usage (CLI):
  python3 bosch_camera.py status
  python3 bosch_camera.py snapshot [<cam-name>] [--live]   # --live: prefer live methods
  python3 bosch_camera.py liveshot [<cam-name>]            # alias: forces live methods
  python3 bosch_camera.py live     [<cam-name>]            # open RTSP stream in VLC
  python3 bosch_camera.py download [<cam-name>] [--limit N] [--snaps-only] [--clips-only]
  python3 bosch_camera.py events   [<cam-name>] [--limit N] [--clip EVENT_ID]
  python3 bosch_camera.py privacy-sound [<cam-name>] [on|off]
  python3 bosch_camera.py rules    [<cam-name>] [add|edit|delete]
  python3 bosch_camera.py friends  [invite|share|unshare|resend|remove]
  python3 bosch_camera.py rename   <cam-name> "New Name"
  python3 bosch_camera.py profile  [edit --display-name NAME --marketing on|off]
  python3 bosch_camera.py account                          # feature flags, contracts, purchases
  python3 bosch_camera.py config                           # show current config
  python3 bosch_camera.py rescan                           # re-discover cameras
"""

import os
import sys
import json
import time
import shutil
import signal
import datetime
import argparse
import threading
import subprocess
import urllib3

import requests
from requests.adapters import HTTPAdapter
from typing import Optional

# Suppress InsecureRequestWarning only for local camera calls (self-signed certs).
# Cloud API and Keycloak calls use verify=True and do not trigger this warning.
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

# ─────────────────────────────────────────────────────────────────────────────
BASE_DIR    = os.path.dirname(os.path.abspath(__file__))
CONFIG_FILE = os.path.join(BASE_DIR, "bosch_config.json")
CLOUD_API   = "https://residential.cbs.boschsecurity.com"
VERSION     = "10.2.1"

DELAY = 0.5   # seconds between download requests (rate-limit protection)

# Human-readable display names for camera hardware versions
HW_DISPLAY_NAMES = {
    "INDOOR": "360 Innenkamera",
    "OUTDOOR": "Eyes Außenkamera",
    "CAMERA_360": "360 Innenkamera",
    "CAMERA_EYES": "Eyes Außenkamera",
    "HOME_Eyes_Outdoor": "Eyes Außenkamera II",
    "HOME_Eyes_Indoor": "Eyes Innenkamera II",
    "CAMERA_OUTDOOR_GEN2": "Eyes Außenkamera II",
    "CAMERA_INDOOR_GEN2": "Eyes Innenkamera II",
}

# ConnectionType enum — confirmed working values (discovered 2026-03-19)
# REMOTE = cloud proxy snap.jpg (fast ~1.5s, no credentials needed)
# LOCAL  = direct LAN snap.jpg (slow ~15s Digest auth, same quality)
# Use REMOTE first for all operations — it is faster than LOCAL despite going via cloud.
LIVE_TYPE_CANDIDATES = [
    "REMOTE",   # ✅ cloud proxy — faster (1.5s vs 15s for LOCAL)
    "LOCAL",    # ✅ LAN direct — fallback if cloud unavailable
]

DEFAULT_CONFIG = {
    "account": {
        "username":      "",
        "password":      "",
        "bearer_token":  "",
        "refresh_token": "",
        "_note": (
            "Set username (your Bosch SingleKey ID email). "
            "Run 'python3 get_token.py' to get tokens automatically via browser login. "
            "After first login the refresh_token enables silent renewal forever."
        ),
    },
    "cameras": {
        # Auto-populated on first run. Example entry:
        # "MyCam": {
        #   "id":              "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        #   "name":            "MyCam",
        #   "model":           "CAMERA_EYES",
        #   "firmware":        "...",
        #   "mac":             "xx:xx:xx:xx:xx:xx",
        #   "download_folder": "MyCam",
        #   "local_ip":        "",   ← optional: set for local snap.jpg access
        #   "local_username":  "",   ← local camera Digest auth username
        #   "local_password":  "",   ← local camera Digest auth password
        #   "last_live": { "rtsp_url": "", "proxy_url": "", "cookie": "" }
        # }
    },
    "settings": {
        "download_base_path":    "",
        "scan_interval_seconds": 30,
        "request_delay_seconds": 0.5,
        "_note": (
            "download_base_path: folder for downloaded events. "
            "Empty = use this script's directory. "
            "local_ip / local_username / local_password per camera: "
            "enables direct local snap.jpg (HTTP Digest auth). "
            "local_ip and credentials are optional — cloud API works without them."
        ),
    },
}
# ─────────────────────────────────────────────────────────────────────────────


# ══════════════════════════ CONFIG MANAGEMENT ═════════════════════════════════

def load_config() -> dict:
    """Load config from file. Creates default config if it doesn't exist."""
    if not os.path.exists(CONFIG_FILE):
        _create_default_config()
    with open(CONFIG_FILE, "r") as f:
        cfg = json.load(f)
    # Merge in any missing keys from DEFAULT_CONFIG (forward-compat)
    _merge_defaults(cfg, DEFAULT_CONFIG)
    return cfg


def save_config(cfg: dict) -> None:
    """Save config to file.

    Serialized via _CONFIG_LOCK so concurrent writes (main thread saving a fresh
    bearer token + FCM credentials-update callback firing from a background
    thread) cannot interleave. Written via tmpfile + os.replace so readers
    never see a half-written JSON — process crash mid-write leaves the
    previous file intact instead of a truncated one.
    """
    with _CONFIG_LOCK:
        tmp_path = f"{CONFIG_FILE}.tmp.{os.getpid()}"
        try:
            with open(tmp_path, "w") as f:
                json.dump(cfg, f, indent=2)
                f.flush()
                os.fsync(f.fileno())
            os.chmod(tmp_path, 0o600)
            os.replace(tmp_path, CONFIG_FILE)
        except Exception:
            try:
                os.remove(tmp_path)
            except OSError:
                pass
            raise


def _create_default_config() -> None:
    """Create a new config file with defaults and print instructions."""
    save_config(DEFAULT_CONFIG)
    print(f"\n✅  Created config file: {CONFIG_FILE}")
    print("    Edit it to add your credentials, or continue — the script will prompt you.\n")


def _merge_defaults(cfg: dict, defaults: dict) -> None:
    """Recursively add missing keys from defaults into cfg (in-place)."""
    for key, val in defaults.items():
        if key not in cfg:
            cfg[key] = val
        elif isinstance(val, dict) and isinstance(cfg[key], dict):
            _merge_defaults(cfg[key], val)


# ══════════════════════════ TOKEN MANAGEMENT ══════════════════════════════════

def _is_token_expired(token: str) -> bool:
    """Return True if the JWT bearer token is expired or expiring within 60s."""
    import base64 as _b64, json as _json
    try:
        parts = token.split(".")
        if len(parts) >= 2:
            pad  = len(parts[1]) % 4
            body = _b64.urlsafe_b64decode(parts[1] + "=" * pad)
            exp  = _json.loads(body).get("exp", 0)
            return exp > 0 and (exp - time.time()) < 60
    except Exception:
        pass
    return False


def _is_token_near_expiry(token_str: str, buffer_secs: int = 60) -> bool:
    """Return True if the JWT bearer token expires within buffer_secs seconds.

    Fail-safe: returns True (treat as near-expiry) if decoding fails.
    Uses only stdlib: base64, json, time.
    """
    import base64 as _b64, json as _json
    try:
        parts = token_str.split(".")
        if len(parts) >= 2:
            pad  = len(parts[1]) % 4
            body = _b64.urlsafe_b64decode(parts[1] + "=" * pad)
            exp  = _json.loads(body).get("exp", 0)
            return exp == 0 or (exp - time.time()) < buffer_secs
    except Exception:
        pass
    return True


def get_token(cfg: dict) -> str:
    """
    Return a valid Bearer token. Tries in order:
      1. Saved bearer_token in config (if not expired)
      2. Silent renewal via refresh_token (auto, no user interaction)
      3. Browser login via get_token.py (auto-opens browser)
      4. Manual paste as last resort
    """
    token = cfg["account"].get("bearer_token", "").strip()
    if token and not _is_token_expired(token):
        return token

    # Token expired or missing — try silent renewal first
    refresh = cfg["account"].get("refresh_token", "").strip()
    if refresh:
        try:
            from get_token import _do_refresh
            if token:  # only print if we had a token (i.e. it expired)
                print("  🔄  Token expired — renewing automatically via refresh_token...")
            tokens = _do_refresh(refresh)
            if tokens:
                new_token   = tokens.get("access_token", "")
                new_refresh = tokens.get("refresh_token", refresh)
                cfg["account"]["bearer_token"]  = new_token
                cfg["account"]["refresh_token"] = new_refresh
                save_config(cfg)
                print("  ✅  Token renewed silently.")
                return new_token
        except ImportError:
            pass
        except Exception as e:
            print(f"  ⚠️   Silent renewal failed: {e}")

    if token:
        return token  # Expired but renewal failed — return as-is and let the API reject it

    # Try get_token.py auto-flow (refresh + browser login)
    try:
        from get_token import get_token_auto
        print("  🔑  No token in config — trying automatic token retrieval...")
        new_token = get_token_auto(cfg)
        if new_token:
            return new_token
    except ImportError:
        # get_token.py not in path — fall through to manual
        pass
    except Exception as e:
        print(f"  ⚠️   Auto-token failed: {e}")

    # Manual fallback
    print("\n  ⚠️   Could not obtain token automatically.")
    print("  Options:")
    print("    • Run: python3 get_token.py  (browser login, saves token automatically)")
    print("    • Or paste a Bearer token captured from the Bosch Smart Home Camera app")
    print("      (See README.md for mitmproxy instructions)\n")
    token = input("  Paste Bearer token (or press Enter to exit): ").strip()
    if not token:
        print("  ❌  No token. Exiting.")
        sys.exit(1)
    cfg["account"]["bearer_token"] = token
    save_config(cfg)
    print(f"  💾  Token saved.")
    return token


def check_token_age(cfg: dict) -> str:
    """Return human-readable token expiry decoded from JWT claims."""
    import base64 as _b64, json as _json
    token = cfg["account"].get("bearer_token", "").strip()
    if not token:
        return "no token"
    try:
        parts = token.split(".")
        if len(parts) >= 2:
            pad  = len(parts[1]) % 4
            body = _b64.urlsafe_b64decode(parts[1] + "=" * pad)
            info = _json.loads(body)
            exp  = info.get("exp", 0)
            if exp:
                exp_dt = datetime.datetime.fromtimestamp(exp)
                diff   = exp_dt - datetime.datetime.now()
                mins   = int(diff.total_seconds() / 60)
                if mins > 5:
                    return f"valid, expires in ~{mins}m ✅"
                elif mins > 0:
                    return f"expires in ~{mins}m ⚠️"
                else:
                    return f"EXPIRED {abs(mins)}m ago ❌  — run: python3 bosch_camera.py token fix"
    except Exception:
        pass
    # Fallback to file mtime
    mtime = os.path.getmtime(CONFIG_FILE)
    age   = datetime.datetime.now() - datetime.datetime.fromtimestamp(mtime)
    mins  = int(age.total_seconds() / 60)
    if mins < 60:
        return f"~{mins} min old ✅"
    elif mins < 120:
        return f"~{mins} min old ⚠️  (may be expired)"
    else:
        return f"~{mins} min old ❌  — run: python3 bosch_camera.py token fix"


def handle_401(cfg: dict) -> str:
    """Called when API returns 401. Clears token, prompts for a new one."""
    print("\n  ❌  Bearer token expired (HTTP 401).")
    cfg["account"]["bearer_token"] = ""
    return get_token(cfg)


# ══════════════════════════ SESSION ═══════════════════════════════════════════

# Cached global session — reuses a single TCP/TLS connection pool across all API
# calls (avoids handshake-per-request). Token updates only touch the Authorization
# header, so the underlying pool stays warm.
_HTTP_SESSION: Optional[requests.Session] = None


def make_session(token: str) -> requests.Session:
    """Return the cached module-level session, updating the Bearer token header.

    On first call, creates a requests.Session with a connection-pooled HTTPAdapter
    (pool_connections=10, pool_maxsize=20, max_retries=0 — retries are handled
    explicitly by _request_with_retry). Subsequent calls just swap the token on
    the existing session so connections are reused.
    """
    global _HTTP_SESSION
    if _HTTP_SESSION is None:
        s = requests.Session()
        adapter = HTTPAdapter(pool_connections=10, pool_maxsize=20, max_retries=0)
        s.mount("https://", adapter)
        s.mount("http://", adapter)
        s.verify = False
        _HTTP_SESSION = s
    _HTTP_SESSION.headers.update({
        "Authorization": f"Bearer {token}",
        "Accept": "application/json",
    })
    return _HTTP_SESSION


# Lock serializing bosch_config.json writes (FCM creds-update callback may fire
# from a background thread while the main thread is also saving tokens).
_CONFIG_LOCK = threading.Lock()


# Set by SIGTERM/SIGINT handlers so long-running loops (watch, FCM) can exit
# cleanly instead of relying solely on KeyboardInterrupt propagation.
_STOP_REQUESTED = threading.Event()


def _install_stop_handlers() -> None:
    """Install SIGINT/SIGTERM handlers that flip _STOP_REQUESTED.

    Safe to call multiple times — later calls just re-install the same handler.
    Only installs in the main thread (signal.signal() raises otherwise).
    """
    if threading.current_thread() is not threading.main_thread():
        return
    def _handler(signum, frame):
        _STOP_REQUESTED.set()
    try:
        signal.signal(signal.SIGINT, _handler)
        signal.signal(signal.SIGTERM, _handler)
    except (ValueError, OSError):
        # signal.signal() can fail in odd embedding contexts — ignore.
        pass


def _request_with_retry(session: requests.Session, method: str, url: str,
                         max_attempts: int = 3, **kwargs) -> requests.Response:
    """Issue an HTTP request with exponential backoff on transient failures.

    Retries only on HTTP 5xx responses and on requests.exceptions.Timeout /
    ConnectionError. Auth/client errors (401/403/404, etc.) pass through on the
    first attempt — the caller decides how to react.

    Backoff: 1s, 2s, 4s between attempts (max_attempts=3 → up to 2 retries).
    """
    last_exc: Optional[BaseException] = None
    for attempt in range(max_attempts):
        try:
            r = session.request(method, url, **kwargs)
        except (requests.exceptions.Timeout, requests.exceptions.ConnectionError) as e:
            last_exc = e
            if attempt == max_attempts - 1:
                raise
            time.sleep(2 ** attempt)
            continue
        # Retry only on server-side errors.
        if 500 <= r.status_code < 600 and attempt < max_attempts - 1:
            time.sleep(2 ** attempt)
            continue
        return r
    # Unreachable — loop either returns a response or re-raises. Keep for safety.
    if last_exc is not None:
        raise last_exc
    raise RuntimeError("unreachable: _request_with_retry loop exited without result")


# ══════════════════════════ CAMERA DISCOVERY ══════════════════════════════════

def discover_cameras(cfg: dict, session: requests.Session) -> dict:
    """
    GET /v11/video_inputs → discover all cameras.
    Returns dict keyed by camera name (title):
      {
        "MyCam": { "id": "...", "name": "MyCam", "model": "...",
                    "firmware": "...", "mac": "...", "download_folder": "MyCam" },
        ...
      }
    Saves discovered cameras to config.
    """
    r = session.get(f"{CLOUD_API}/v11/video_inputs", timeout=15)
    if r.status_code == 401:
        return {}
    r.raise_for_status()

    cam_list = r.json()
    cameras  = {}
    for cam in cam_list:
        name = cam.get("title", cam.get("id", "unknown"))
        # Keep existing local config if camera already known
        existing = cfg.get("cameras", {}).get(name, {})
        feat = cam.get("featureSupport", {})
        cameras[name] = {
            "id":              cam.get("id", ""),
            "name":            name,
            "model":           cam.get("hardwareVersion", "CAMERA"),
            "firmware":        cam.get("firmwareVersion", ""),
            "mac":             cam.get("macAddress", ""),
            "download_folder": name,
            "local_ip":        existing.get("local_ip", ""),
            "local_username":  existing.get("local_username", ""),
            "local_password":  existing.get("local_password", ""),
            "has_light":       feat.get("light", False),
            "pan_limit":       feat.get("panLimit", 0),
        }
        # Ask for local IP if not already set
        if not cameras[name]["local_ip"]:
            print(f"\n  📷  Camera: {name}")
            ip = input(f"     Local IP address (e.g. 192.168.1.100) — press Enter to skip: ").strip()
            if ip:
                cameras[name]["local_ip"] = ip
    cfg["cameras"] = cameras
    save_config(cfg)
    print(f"  💾  Discovered {len(cameras)} camera(s) → saved to {CONFIG_FILE}")
    return cameras


def get_cameras(cfg: dict, session: requests.Session) -> dict:
    """Return cameras from config; auto-discover if none are saved yet."""
    if not cfg.get("cameras"):
        print("  🔍  No cameras in config — auto-discovering...")
        return discover_cameras(cfg, session)
    return cfg["cameras"]


def resolve_cam(cfg: dict, key: str | None) -> dict:
    """
    Resolve a partial camera name to the full cameras dict entry.
    If key is None → return all cameras.
    If key matches exactly or case-insensitively → return that single camera dict.
    """
    cameras = cfg.get("cameras", {})
    if not key:
        return cameras
    # Exact match
    if key in cameras:
        return {key: cameras[key]}
    # Case-insensitive partial match
    key_lower = key.lower()
    matches = {k: v for k, v in cameras.items() if key_lower in k.lower()}
    if len(matches) == 1:
        return matches
    if len(matches) > 1:
        names = ", ".join(matches.keys())
        print(f"  ⚠️   Ambiguous camera name '{key}' — matches: {names}")
        sys.exit(1)
    print(f"  ❌  Camera '{key}' not found in config. Known: {', '.join(cameras.keys())}")
    print(f"      Run 'python3 bosch_camera.py rescan' to re-discover cameras.")
    sys.exit(1)


# ══════════════════════════ API HELPERS ═══════════════════════════════════════

def api_ping(session: requests.Session, cam_id: str) -> str:
    try:
        r = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/ping", timeout=10)
        if r.status_code == 200:
            return r.text.strip().strip('"')
        return f"HTTP {r.status_code}"
    except Exception as e:
        return f"ERROR: {e}"


def api_get_events(session: requests.Session, cam_id: str, limit: int = 400) -> list:
    r = _request_with_retry(
        session, "GET",
        f"{CLOUD_API}/v11/events?videoInputId={cam_id}&limit={limit}",
        timeout=30,
    )
    if r.status_code == 401:
        return []
    r.raise_for_status()
    return r.json()


def api_mark_events_read(session: requests.Session, event_ids: list[str]) -> bool:
    """Mark events as read on the Bosch cloud via PUT /v11/events.

    The /v11/events/bulk endpoint only supports `{ids, action: "DELETE"}` —
    there is no bulk mark-as-read. Returns True if at least one PUT succeeded.
    """
    if not event_ids:
        return True

    success = False
    for eid in event_ids:
        try:
            r = session.put(
                f"{CLOUD_API}/v11/events",
                json={"id": eid, "isRead": True},
                timeout=5,
            )
            if r.status_code in (200, 204):
                success = True
        except Exception:
            pass
    return success


def api_get_camera(session: requests.Session, cam_id: str) -> dict | None:
    """
    GET /v11/video_inputs/{cam_id} — fetch a single camera object by ID.
    Returns the camera dict or None on error.
    """
    try:
        r = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}", timeout=15)
        if r.status_code == 200:
            return r.json()
    except Exception:
        pass
    return None


# ══════════════════════════ OPEN FILE / VLC ═══════════════════════════════════

def open_file(path: str) -> None:
    if sys.platform == "darwin":
        subprocess.Popen(["open", path])
    elif sys.platform.startswith("linux"):
        subprocess.Popen(["xdg-open", path])
    else:
        os.startfile(path)


def open_vlc(url: str, user: str = "", password: str = "", token: str = "") -> None:
    # Prefer ffplay/mpv for RTSP — they support custom headers for Bearer auth.
    # VLC does not support Authorization headers for RTSP.
    if url.startswith("rtsp://"):
        players = [
            shutil.which("ffplay"),
            shutil.which("mpv"),
            shutil.which("vlc"),
            "/Applications/VLC.app/Contents/MacOS/VLC",
        ]
    else:
        players = [
            shutil.which("vlc"),
            "/Applications/VLC.app/Contents/MacOS/VLC",
            shutil.which("mpv"),
            shutil.which("ffplay"),
        ]
    player = next((p for p in players if p and os.path.exists(p)), None)
    if not player:
        print(f"\n  ❌  No media player found (VLC / mpv / ffplay).")
        print(f"      Install:  brew install ffmpeg   # or brew install --cask vlc")
        print(f"      Stream URL:   {url}")
        return

    print(f"\n  ▶️   Opening in {os.path.basename(player)}: {url}")

    name = os.path.basename(player).lower()
    if "ffplay" in name:
        cmd = [player, "-rtsp_transport", "tcp"]
        if token:
            cmd += ["-headers", f"Authorization: Bearer {token}\r\n"]
        cmd += [url]
    elif "mpv" in name:
        cmd = [player]
        if token:
            cmd += [f"--http-header-fields=Authorization: Bearer {token}"]
        cmd += [url]
    else:
        # VLC — embed creds in URL if provided, otherwise try as-is
        open_url = url
        if user and password and url.startswith("rtsp://"):
            from urllib.parse import quote
            host_part = url[len("rtsp://"):]
            open_url = f"rtsp://{quote(user, safe='')}:{quote(password, safe='')}@{host_part}"
        cmd = [player, open_url]
        if token and "vlc" in name:
            cmd += ["--http-cookie", f"HcsoB={token[:20]}"]

    if user:
        print(f"  🔑  Using credentials: {user}")
    subprocess.Popen(cmd)


# ══════════════════════════ COMMANDS ══════════════════════════════════════════

def cmd_status(cfg: dict, args) -> None:
    """Show all cameras with ONLINE/OFFLINE status."""
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)

    print(f"\n── Bosch Smart Home Cameras ────────────────────────────────")
    print(f"   Token age: {check_token_age(cfg)}\n")

    for name, cam_info in cameras.items():
        status = api_ping(session, cam_info["id"])
        if status == "ONLINE":
            icon = "🟢"
        elif status.startswith("UPDATING"):
            icon = "🔄"
            status = "UPDATING (firmware)"
        else:
            icon = "🔴"
        print(f"  {icon}  {name}")
        print(f"      ID:      {cam_info['id']}")
        print(f"      Model:   {cam_info['model']}   FW: {cam_info['firmware']}")
        print(f"      MAC:     {cam_info['mac']}")
        print(f"      Status:  {status}")
        print()


def cmd_events(cfg: dict, args) -> None:
    """Show latest events — removed (cloud event listing no longer available)."""
    print("  ⚠️  Events command has been removed.")
    return



# ══════════════════════════ LIVE SNAPSHOT METHODS ═══════════════════════════

def snap_from_proxy(cam_info: dict, token: str, hq: bool = False,
                     cfg: Optional[dict] = None) -> bytes | None:
    """
    Live snapshot via PUT /connection.
    Tries LOCAL first (faster on home network), then REMOTE (cloud proxy).
    If snap.jpg returns 404 (proxy session expired), automatically re-requests
    a fresh connection and retries once.
    hq=True requests highQualityVideo in the connection payload.
    If cfg is provided and we receive a 401 on PUT /connection, refresh the
    token once and retry. On second 401 we fail hard with a clear message.
    Returns JPEG bytes or None.
    """
    cam_id  = cam_info.get("id", "")
    # Mutable list so the inner closure can update the header after a token refresh.
    headers_box = [{"Authorization": f"Bearer {token}", "Content-Type": "application/json"}]

    def _put_connection(conn_type: str) -> requests.Response:
        """PUT /connection with one-shot token refresh on 401."""
        r = requests.put(
            f"{CLOUD_API}/v11/video_inputs/{cam_id}/connection",
            headers=headers_box[0],
            json={"type": conn_type, "highQualityVideo": hq},
            timeout=15,
        )
        if r.status_code == 401 and cfg is not None:
            print("  🔄  Token expired (401) — refreshing once...")
            try:
                new_token = get_token(cfg)
            except Exception as e:
                print(f"  ❌  Token refresh failed: {e}")
                print("      Run `bosch-camera login` (or `python3 get_token.py`).")
                return r
            headers_box[0] = {"Authorization": f"Bearer {new_token}",
                              "Content-Type": "application/json"}
            # Also update the cached session so subsequent calls use the new token.
            make_session(new_token)
            r = requests.put(
                f"{CLOUD_API}/v11/video_inputs/{cam_id}/connection",
                headers=headers_box[0],
                json={"type": conn_type, "highQualityVideo": hq},
                timeout=15,
            )
            if r.status_code == 401:
                print("  ❌  Still 401 after refresh — token could not be refreshed. "
                      "Run `bosch-camera login`.")
        return r

    def _fetch_snap(conn_type: str) -> bytes | None:
        label = "local" if conn_type == "LOCAL" else "cloud proxy"
        print(f"  🌐  Opening {label} connection...")
        r = _put_connection(conn_type)
        if r.status_code != 200:
            return None
        data     = r.json()
        urls     = data.get("urls", [])
        scheme   = data.get("imageUrlScheme", "https://{url}/snap.jpg")
        api_user = data.get("user") or ""
        api_pass = data.get("password") or ""
        if not urls:
            return None
        snap_url = scheme.replace("{url}", urls[0])
        snap_timeout = 5 if conn_type == "LOCAL" else 15
        # snap.jpg may come from local camera (self-signed cert) — verify=False required
        if api_user and api_pass:
            from requests.auth import HTTPDigestAuth
            snap_r = requests.get(snap_url, auth=HTTPDigestAuth(api_user, api_pass),
                                  verify=False, timeout=snap_timeout)
        else:
            snap_r = requests.get(snap_url, verify=False, timeout=snap_timeout)
        if snap_r.status_code == 200 and snap_r.headers.get("Content-Type", "").startswith("image"):
            print(f"  ✅  Live snapshot ({label}): {len(snap_r.content):,} bytes")
            return snap_r.content
        elif snap_r.status_code == 404:
            print(f"  ⚠️   Proxy session expired (404) — re-requesting connection...")
            # Retry once with a fresh connection (reuses the refreshed token if
            # the first PUT already triggered a token renewal).
            r2 = _put_connection(conn_type)
            if r2.status_code == 200:
                data2     = r2.json()
                urls2     = data2.get("urls", [])
                scheme2   = data2.get("imageUrlScheme", "https://{url}/snap.jpg")
                api_user2 = data2.get("user") or ""
                api_pass2 = data2.get("password") or ""
                if urls2:
                    snap_url2 = scheme2.replace("{url}", urls2[0])
                    if api_user2 and api_pass2:
                        from requests.auth import HTTPDigestAuth
                        snap_r2 = requests.get(snap_url2, auth=HTTPDigestAuth(api_user2, api_pass2),
                                               verify=False, timeout=snap_timeout)
                    else:
                        snap_r2 = requests.get(snap_url2, verify=False, timeout=snap_timeout)
                    if snap_r2.status_code == 200 and snap_r2.headers.get("Content-Type", "").startswith("image"):
                        print(f"  ✅  Live snapshot ({label}, retry): {len(snap_r2.content):,} bytes")
                        return snap_r2.content
            print(f"  ⚠️   {label} snap retry also failed")
            return None
        else:
            print(f"  ⚠️   {label} snap returned HTTP {snap_r.status_code}")
            return None

    for conn_type in LIVE_TYPE_CANDIDATES:
        try:
            result = _fetch_snap(conn_type)
            if result:
                return result
        except Exception as e:
            label = "local" if conn_type == "LOCAL" else "cloud proxy"
            print(f"  ⚠️   {label} error: {e}")
    return None


def snap_from_local(cam_info: dict) -> bytes | None:
    """
    Method 2 — Local camera snap.jpg via HTTP Digest authentication.
    Direct access to the camera at https://<local_ip>/snap.jpg
    Returns 1920×1080 JPEG bytes or None.

    Credentials are randomly generated by the SHC at pairing time.
    Capture via mitmproxy and store in config under local_ip / local_username / local_password.

    WARNING: Excessive requests to the local camera IP can break the connection,
    causing the SHC to regenerate random credentials. Use sparingly.
    """
    local_ip   = cam_info.get("local_ip", "")
    username   = cam_info.get("local_username", "")
    password   = cam_info.get("local_password", "")

    if not local_ip or not username or not password:
        return None

    # Append ?JpegSize=1206 — without it the camera triggers a slow on-demand
    # full-sensor capture (~6–10 s when idle). With it, the cached path serves
    # in ~1.4 s. Verified empirically; matches HA integration v10.4.5 fix.
    url = f"https://{local_ip}/snap.jpg?JpegSize=1206"
    print(f"  🏠  Trying local camera snapshot: {url}")
    try:
        from requests.auth import HTTPDigestAuth
        r = requests.get(
            url,
            auth=HTTPDigestAuth(username, password),
            timeout=10,
            verify=False,
        )
        if r.status_code == 200 and r.headers.get("Content-Type", "").startswith("image"):
            print(f"  ✅  Local snapshot: {len(r.content):,} bytes  (1920×1080)")
            return r.content
        else:
            print(f"  ⚠️   Local camera returned {r.status_code}")
    except Exception as e:
        print(f"  ⚠️   Local camera error: {e}")
    return None


def snap_from_events(session, cam_info: dict) -> tuple[bytes | None, str]:
    """
    Method 3 — Latest event snapshot (cloud API, motion-triggered).
    Returns (jpeg_bytes, timestamp_str) or (None, "").
    Only updates when the camera detects motion — not a live view.
    """
    events = api_get_events(session, cam_info["id"], limit=10)
    for ev in events:
        img_url = ev.get("imageUrl")
        if not img_url:
            continue
        try:
            r = session.get(img_url, timeout=20)
            if r.status_code == 200:
                ts = ev.get("timestamp", "")[:19]
                return r.content, ts
        except Exception:
            pass
    return None, ""


def _save_and_open(data: bytes, name: str, ts: str, method: str) -> str:
    """Save image bytes to file and open in Preview. Returns file path."""
    safe_name = name.replace(" ", "_")
    ts_safe   = ts.replace(":", "-").replace("T", "_") if ts else \
                datetime.datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
    fn   = f"snapshot_{safe_name}_{ts_safe}_{method}.jpg"
    path = os.path.join(BASE_DIR, fn)
    with open(path, "wb") as f:
        f.write(data)
    print(f"  💾  {path}  ({len(data):,} bytes)")
    open_file(path)
    return path


# ─────────────────────────────────────────────────────────────────────────────
def cmd_snapshot(cfg: dict, args) -> None:
    """
    Fetch and open the best available snapshot for a camera.

    Without --live: shows latest event snapshot (cloud events API).
    With --live:    tries methods in order:
                      1. Cloud proxy live snap (if live connection previously opened)
                      2. Local camera snap.jpg (if local_ip + credentials in config)
                      3. Latest event snapshot (fallback)
    --hq: request highQualityVideo=true in PUT /connection (higher resolution).
    """
    token   = get_token(cfg)
    session = make_session(token)
    session.headers["Accept"] = "*/*"
    cameras = get_cameras(cfg, session)
    cams    = resolve_cam(cfg, getattr(args, "cam", None))
    live    = getattr(args, "live", False)
    quality = getattr(args, "quality", None)
    if quality == "high":
        hq = True
    elif quality is not None:
        hq = False
    else:
        hq = getattr(args, "hq", False)

    for name, cam_info in cams.items():
        mode_str = "Live Snapshot" if live else "Latest Event Snapshot"
        print(f"\n── {mode_str}: {name} ──────────────────────────────────────")

        if live:
            # ── Method 1: Cloud proxy live snap ───────────────────────────────
            data = snap_from_proxy(cam_info, token, hq=hq, cfg=cfg)
            if data:
                _save_and_open(data, name, "", "proxy_live")
                continue

            # ── Method 2: Local camera snap.jpg ───────────────────────────────
            data = snap_from_local(cam_info)
            if data:
                _save_and_open(data, name, "", "local_live")
                continue

            print("  ℹ️   Live methods unavailable:")
            if not cam_info.get("last_live", {}).get("proxy_url"):
                print("       • Cloud proxy: no live connection opened yet")
                print("         → Press 'Open Live Stream' button in HA, or run: live " + name)
            if not cam_info.get("local_ip"):
                print("       • Local: no local_ip set in config")
                print(f"         → Edit {CONFIG_FILE} and set local_ip, local_username, local_password")
            print("  ↩️   Falling back to latest event snapshot...\n")

        # ── Method 3 (or default): Latest event snapshot ──────────────────────
        data, ts = snap_from_events(session, cam_info)
        if data:
            _save_and_open(data, name, ts, "event")
            if not live:
                print(f"  ℹ️   This is a motion-triggered snapshot from {ts[:10]},")
                print(f"       not a live view. Use '--live' for live snapshot methods.")
        else:
            print("  ⚠️   No snapshot available (token expired or no events).")


def _live_snap_loop(snap_url: str, cam_name: str, interval: float = 1.0) -> None:
    """
    Live view: serves snap.jpg frames as a local MJPEG stream, then opens ffplay on it.
    ffplay connects to http://localhost:PORT and receives a continuous MJPEG feed.
    Press Q in the ffplay window or Ctrl+C in the terminal to stop.
    """
    import threading
    import http.server
    import socket

    ffplay = shutil.which("ffplay") or "/opt/homebrew/bin/ffplay"
    if not os.path.exists(ffplay):
        ffplay = None

    if not ffplay:
        print(f"\n  ❌  ffplay not found. Install with: brew install ffmpeg\n")
        return

    # Find a free port
    with socket.socket() as s:
        s.bind(("127.0.0.1", 0))
        port = s.getsockname()[1]

    stop_event = threading.Event()
    frame_lock  = threading.Lock()
    current_frame: list = [None]  # [bytes | None]

    # ── Fetcher thread: polls snap.jpg ────────────────────────────────────────
    def fetcher():
        count = 0
        while not stop_event.is_set():
            t0 = time.time()
            try:
                r = requests.get(snap_url, verify=False, timeout=10)
                if r.status_code == 200 and r.headers.get("Content-Type", "").startswith("image"):
                    with frame_lock:
                        current_frame[0] = r.content
                    count += 1
                    print(f"\r  🖼️   Frame {count}  {len(r.content):,} bytes", end="", flush=True)
                elif r.status_code == 404:
                    print(f"\n  ⏰  Proxy session expired after {count} frames.")
                    stop_event.set()
                    break
            except Exception:
                pass
            elapsed = time.time() - t0
            remaining = interval - elapsed
            if remaining > 0:
                stop_event.wait(remaining)

    # ── MJPEG HTTP server ─────────────────────────────────────────────────────
    class MJPEGHandler(http.server.BaseHTTPRequestHandler):
        def log_message(self, *args): pass  # silence request logs

        def do_GET(self):
            self.send_response(200)
            self.send_header("Content-Type", "multipart/x-mixed-replace; boundary=--frame")
            self.end_headers()
            try:
                while not stop_event.is_set():
                    with frame_lock:
                        frame = current_frame[0]
                    if frame:
                        header = (
                            f"--frame\r\n"
                            f"Content-Type: image/jpeg\r\n"
                            f"Content-Length: {len(frame)}\r\n\r\n"
                        ).encode()
                        self.wfile.write(header)
                        self.wfile.write(frame)
                        self.wfile.write(b"\r\n")
                        self.wfile.flush()
                    time.sleep(interval)
            except (BrokenPipeError, ConnectionResetError):
                pass

    server = http.server.ThreadingHTTPServer(("127.0.0.1", port), MJPEGHandler)
    server.daemon_threads = True

    threading.Thread(target=fetcher, daemon=True).start()

    # Wait for first frame
    print(f"\n  📺  Starting live view (press Q in player window or Ctrl+C to stop)...")
    for _ in range(30):
        if current_frame[0]:
            break
        time.sleep(0.2)
    else:
        print("  ❌  No frames received.")
        stop_event.set()
        return

    def _serve():
        server.serve_forever()

    server_thread = threading.Thread(target=_serve, daemon=True)
    server_thread.start()

    mjpeg_url = f"http://127.0.0.1:{port}/"

    # On macOS, ffplay launched as a subprocess doesn't get a window session.
    # Use 'open -a' to properly bring the player to the foreground.
    if sys.platform == "darwin":
        # Try mpv first (works as CLI subprocess), then VLC via open -a
        mpv = shutil.which("mpv")
        vlc = "/Applications/VLC.app/Contents/MacOS/VLC"
        if mpv:
            cmd = [mpv, "--no-terminal", "--title", f"Live: {cam_name}", mjpeg_url]
            print(f"  ▶️   Launching mpv: {mjpeg_url}")
            proc = subprocess.Popen(cmd, stderr=subprocess.DEVNULL)
        elif os.path.exists(vlc):
            cmd = ["open", "-a", "VLC", mjpeg_url]
            print(f"  ▶️   Launching VLC: {mjpeg_url}")
            proc = subprocess.Popen(cmd, stderr=subprocess.DEVNULL)
        else:
            # ffplay via open — write a tiny shell script and open it
            script = os.path.join(BASE_DIR, "_live_ffplay.sh")
            with open(script, "w") as f:
                f.write(f"#!/bin/sh\n{ffplay} -loglevel warning -f mjpeg -window_title 'Live: {cam_name}' '{mjpeg_url}'\n")
            os.chmod(script, 0o755)
            cmd = ["open", "-W", "-a", "Terminal", script]
            print(f"  ▶️   Launching ffplay via Terminal: {mjpeg_url}")
            proc = subprocess.Popen(cmd)
    else:
        cmd = [ffplay, "-loglevel", "warning", "-f", "mjpeg", "-window_title", f"Live: {cam_name}", mjpeg_url]
        print(f"  ▶️   Launching: {' '.join(cmd)}")
        proc = subprocess.Popen(cmd, stderr=subprocess.PIPE)

    try:
        proc.wait()
    except KeyboardInterrupt:
        proc.kill()
    finally:
        stop_event.set()
        server.shutdown()
        print(f"\n  ⏹️   Live view stopped.")


def _start_tls_proxy_sync(cam_host: str, cam_port: int) -> int:
    """Start a local TCP→TLS proxy in a background thread. Returns the local port.

    Bosch cameras use RTSPS (RTSP over TLS) with a self-signed certificate.
    FFmpeg cannot skip TLS verification for RTSP Digest auth properly.
    This proxy accepts plain TCP from FFmpeg and forwards to the camera over TLS.
    FFmpeg handles Digest auth itself — the proxy only unwraps TLS.
    """
    import ssl
    import socket
    import threading
    import select as _select

    ctx = ssl.create_default_context()
    ctx.check_hostname = False
    ctx.verify_mode = ssl.CERT_NONE

    srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
    srv.bind(("127.0.0.1", 0))
    port = srv.getsockname()[1]
    srv.listen(2)

    def _proxy_thread():
        _reconnect_attempts = [0]
        while True:
            try:
                client, _ = srv.accept()
            except OSError:
                break
            conn_start = time.time()
            try:
                raw = socket.create_connection((cam_host, cam_port), timeout=10)
                # TCP keep-alive to prevent OS from dropping idle connections
                raw.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
                try:
                    raw.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPIDLE, 30)
                    raw.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPINTVL, 10)
                    raw.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPCNT, 3)
                except (AttributeError, OSError):
                    pass
                tls = ctx.wrap_socket(raw, server_hostname=cam_host)
            except Exception as _proxy_exc:
                client.close()
                _reconnect_attempts[0] += 1
                if _reconnect_attempts[0] > 3:
                    print(
                        f"  [TLS proxy] {cam_host}:{cam_port} — "
                        f"3 consecutive connection failures, giving up.",
                        file=sys.stderr,
                    )
                    break
                time.sleep(2 ** (_reconnect_attempts[0] - 1))  # 1s, 2s, 4s
                continue
            client.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)

            def _pipe(src, dst, is_cam_to_client=False):
                try:
                    while True:
                        # CAM→Client: no timeout (dark scenes have sparse RTP)
                        # Client→CAM: 120s timeout (FFmpeg sends periodic keepalive)
                        timeout = None if is_cam_to_client else 120
                        r, _, _ = _select.select([src], [], [], timeout)
                        if not r:
                            break
                        data = src.recv(65536)
                        if not data:
                            break
                        dst.sendall(data)
                except Exception:
                    pass
                finally:
                    try: src.close()
                    except Exception: pass
                    try: dst.close()
                    except Exception: pass

            t1 = threading.Thread(target=_pipe, args=(client, tls, False), daemon=True)
            t2 = threading.Thread(target=_pipe, args=(tls, client, True), daemon=True)
            t1.start()
            t2.start()
            # Reset failure counter after the connection stays up 30s+.
            def _reset_on_stable(start, counter):
                t1.join(timeout=30)
                if time.time() - start >= 30:
                    counter[0] = 0
            threading.Thread(
                target=_reset_on_stable,
                args=(conn_start, _reconnect_attempts),
                daemon=True,
            ).start()

    t = threading.Thread(target=_proxy_thread, daemon=True)
    t.start()
    return port


def _open_rtsps_stream(rtsps_url: str, cam_name: str, fallback_snap_url: str = "", use_vlc: bool = False) -> None:
    """
    Open live audio+video stream via rtsps:// (RTSP over TLS on port 443).
    use_vlc=True opens in VLC (macOS only, uses osascript to bring window to front).
    Default uses ffplay. Falls back to snap.jpg MJPEG loop if no player available.
    """
    ffplay = shutil.which("ffplay") or "/opt/homebrew/bin/ffplay"
    mpv    = shutil.which("mpv")
    vlc    = "/Applications/VLC.app/Contents/MacOS/VLC"

    if use_vlc and os.path.exists(vlc):
        # VLC can't skip TLS verification for rtsps://, so proxy via ffmpeg:
        # ffmpeg pulls rtsps:// and re-muxes to MPEG-TS over HTTP on localhost
        ffmpeg = shutil.which("ffmpeg") or "/opt/homebrew/bin/ffmpeg"
        if not ffmpeg or not os.path.exists(ffmpeg):
            print("  ⚠️   ffmpeg not found — needed to proxy stream for VLC. Install: brew install ffmpeg")
            return
        import socket as _socket
        with _socket.socket() as _s:
            _s.bind(("127.0.0.1", 0))
            http_port = _s.getsockname()[1]
        local_url = f"http://127.0.0.1:{http_port}/live"
        ffmpeg_cmd = [
            ffmpeg, "-loglevel", "warning",
            "-rtsp_transport", "tcp", "-tls_verify", "0",
            "-i", rtsps_url,
            "-c", "copy", "-f", "mpegts",
            f"http://127.0.0.1:{http_port}/live",
        ]
        # ffmpeg can't serve HTTP — use pipe to VLC's stdin instead
        # Pipe: ffmpeg → stdout (mpegts) → VLC stdin
        ffmpeg_pipe = [
            ffmpeg, "-loglevel", "warning",
            "-rtsp_transport", "tcp", "-tls_verify", "0",
            "-i", rtsps_url,
            "-c", "copy", "-f", "mpegts", "pipe:1",
        ]
        print(f"  ▶️   Launching VLC via ffmpeg pipe (audio+video)...")
        proxy = subprocess.Popen(ffmpeg_pipe, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)
        proc  = subprocess.Popen([vlc, "-"], stdin=proxy.stdout, stderr=subprocess.DEVNULL)
        proxy.stdout.close()
        time.sleep(1.5)
        subprocess.Popen(["osascript", "-e", 'tell application "VLC" to activate'],
                         stderr=subprocess.DEVNULL)
        try:
            proc.wait()
        except KeyboardInterrupt:
            proc.kill()
        finally:
            proxy.kill()
            print(f"\n  ⏹️   Live view stopped.")
        return
    elif ffplay and os.path.exists(ffplay):
        cmd = [ffplay,
               "-rtsp_transport", "tcp",
               "-tls_verify", "0",
               "-loglevel", "warning",
               "-window_title", f"Live: {cam_name}",
               rtsps_url]
        print(f"  ▶️   Launching ffplay (audio+video): {rtsps_url}")
        proc = subprocess.Popen(cmd)
    elif mpv:
        cmd = [mpv, "--no-terminal", "--title", f"Live: {cam_name}",
               "--rtsp-tls-verification=no", rtsps_url]
        print(f"  ▶️   Launching mpv (audio+video): {rtsps_url}")
        proc = subprocess.Popen(cmd, stderr=subprocess.DEVNULL)
    else:
        print("  ⚠️   No player found (ffplay/mpv) — falling back to snap.jpg MJPEG (video only).")
        print("      Install with: brew install ffmpeg")
        if fallback_snap_url:
            _live_snap_loop(fallback_snap_url, cam_name)
        return

    try:
        proc.wait()
    except KeyboardInterrupt:
        proc.kill()
    finally:
        print(f"\n  ⏹️   Live view stopped.")


def cmd_test_local(cfg: dict, args) -> None:
    """Test LOCAL vs REMOTE connection — dumps full API response, snap timing, RTSP URL.

    Calls PUT /connection with both types and prints:
      • Full raw JSON response (user, password, urls, imageUrlScheme, ...)
      • snap.jpg timing and result
      • Local RTSP URL to try in VLC/ffplay

    Use this to verify LOCAL streaming works and measure the 15-second startup issue.
    """
    token   = get_token(cfg)
    session = make_session(token)
    cams    = resolve_cam(cfg, getattr(args, "cam", None))

    for name, cam_info in cams.items():
        cam_id = cam_info["id"]
        print(f"\n{'─'*60}")
        print(f"  TEST LOCAL CONNECTION: {name}")
        print(f"  Camera ID: {cam_id}")
        print(f"{'─'*60}")
        url = f"{CLOUD_API}/v11/video_inputs/{cam_id}/connection"

        for conn_type in ["LOCAL", "REMOTE"]:
            print(f"\n  ─── type={conn_type} ───────────────────────────")
            t0 = time.time()
            r = session.put(
                url,
                json={"type": conn_type, "highQualityVideo": False},
                headers={"Content-Type": "application/json"},
                timeout=15,
            )
            elapsed = time.time() - t0
            print(f"  PUT /connection → HTTP {r.status_code}  ({elapsed:.2f}s)")

            if r.status_code not in (200, 201):
                print(f"  Response body: {r.text[:400]}")
                continue

            data = r.json()
            print(f"  Full response:\n{json.dumps(data, indent=4)}")

            urls_list = data.get("urls", [])
            user      = data.get("user", "")
            password  = data.get("password", "")
            scheme    = data.get("imageUrlScheme", "https://{url}/snap.jpg")

            if not urls_list:
                print("  ⚠️   No URLs in response.")
                continue

            snap_url = scheme.replace("{url}", urls_list[0])
            print(f"\n  snap.jpg: {snap_url}")
            t1 = time.time()
            try:
                if user and password:
                    from requests.auth import HTTPDigestAuth
                    sr = requests.get(snap_url, auth=HTTPDigestAuth(user, password),
                                      verify=False, timeout=15)
                else:
                    sr = requests.get(snap_url, verify=False, timeout=15)
                snap_elapsed = time.time() - t1
                ct = sr.headers.get("Content-Type", "")
                print(f"  snap.jpg → HTTP {sr.status_code}  ({snap_elapsed:.2f}s)  {ct}")
                if sr.status_code == 200 and "image" in ct:
                    fn   = f"test_{conn_type.lower()}_{name}.jpg"
                    path = os.path.join(BASE_DIR, fn)
                    with open(path, "wb") as f:
                        f.write(sr.content)
                    print(f"  ✅  Saved: {path}  ({len(sr.content):,} bytes)")
                    open_file(path)
            except Exception as e:
                print(f"  ⚠️   snap.jpg error: {e}")

            # Build RTSP URL — use videoUrlScheme from API response
            u = urls_list[0]
            video_scheme = data.get("videoUrlScheme", "")
            if "/" in u:
                # REMOTE: "proxy-NN.live.cbs.boschsecurity.com:42090/{hash}"
                host_port, hash_path = u.split("/", 1)
                proxy_host = host_port.split(":")[0]
                rtsp_url = (
                    f"rtsps://{proxy_host}:443/{hash_path}"
                    f"/rtsp_tunnel?inst=2&enableaudio=1&fmtp=1&maxSessionDuration=3600"
                )
            else:
                # LOCAL: "192.168.x.x:443" — plain rtsp://, credentials URL-encoded
                from urllib.parse import quote as _q
                auth_prefix = f"{_q(user, safe='')}:{_q(password, safe='')}@" if user and password else ""
                rtsp_url = (
                    f"rtsp://{auth_prefix}{u}"
                    f"/rtsp_tunnel?inst=2&enableaudio=1&fmtp=1&maxSessionDuration=3600"
                )
            print(f"\n  RTSP URL:  {rtsp_url}")
            if video_scheme:
                full_url = video_scheme.replace("{url}", u)
                if user and password and "://" in full_url:
                    scheme_part, rest = full_url.split("://", 1)
                    full_url = f"{scheme_part}://{user}:{password}@{rest}"
                print(f"  API scheme: {full_url}")

            if getattr(args, "play", False):
                print(f"  ▶️   Opening stream...")
                _open_rtsps_stream(rtsp_url, name, snap_url)

        print()


def cmd_live(cfg: dict, args) -> None:
    """Open live stream — tries PUT /connection → open VLC on success.

    --hq: request highQualityVideo=true in PUT /connection (higher bitrate stream).
    --inst N: select stream instance (default 2; use 1 for alternative stream).
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cams    = resolve_cam(cfg, getattr(args, "cam", None))

    # Quality preset overrides --hq/--inst
    quality = getattr(args, "quality", None)
    if quality == "high":
        hq   = True
        inst = getattr(args, "inst", 2) if getattr(args, "inst", 2) != 2 else 1
    elif quality == "low":
        hq   = False
        inst = getattr(args, "inst", 2) if getattr(args, "inst", 2) != 2 else 4
    else:
        hq   = getattr(args, "hq", False)
        inst = getattr(args, "inst", 2)

    for name, cam_info in cams.items():
        print(f"\n── Live Stream: {name} ──────────────────────────────────────")
        status = api_ping(session, cam_info["id"])
        if status == "ONLINE":
            icon = "🟢"
        elif status.startswith("UPDATING"):
            icon = "🔄"
        else:
            icon = "🔴"
        print(f"  {icon}  Status: {status}")

        if status != "ONLINE":
            print("  ⚠️   Camera is OFFLINE — live stream not available.")
            continue

        print("  🔄  Opening live connection...")
        url         = f"{CLOUD_API}/v11/video_inputs/{cam_info['id']}/connection"
        result      = None
        result_type = ""

        # --local flag forces LOCAL (direct LAN); default is REMOTE (cloud proxy).
        # LOCAL response gives user/password + LAN IP — credentials embedded in RTSP URL.
        force_local = getattr(args, "local", False)
        type_candidates = ["LOCAL"] if force_local else ["REMOTE", "LOCAL"]
        token_refreshed = False  # refresh the bearer at most once per camera
        for type_val in type_candidates:
            r = session.put(
                url,
                json={"type": type_val, "highQualityVideo": hq},
                headers={"Content-Type": "application/json"},
                timeout=15,
            )
            if r.status_code == 401 and not token_refreshed:
                # One-shot refresh: update the cached session's Authorization
                # header and retry this single connection type immediately.
                print("  🔄  Token expired (401) — refreshing once...")
                try:
                    new_token = get_token(cfg)
                except Exception as e:
                    print(f"  ❌  Token refresh failed: {e}")
                    print("      Run `bosch-camera login` (or `python3 get_token.py`).")
                    break
                token = new_token
                session = make_session(token)
                token_refreshed = True
                r = session.put(
                    url,
                    json={"type": type_val, "highQualityVideo": hq},
                    headers={"Content-Type": "application/json"},
                    timeout=15,
                )
            if r.status_code in (200, 201):
                result      = r.json()
                result_type = type_val
                print(f"  ✅  ConnectionType '{type_val}' worked!")
                break
            elif r.status_code == 401:
                print("  ❌  Token could not be refreshed — run `bosch-camera login`.")
                break

        if result:
            urls       = result.get("urls", [])
            img_scheme = result.get("imageUrlScheme", "https://{url}/snap.jpg")
            user       = result.get("user") or ""
            password   = result.get("password") or ""

            proxy_url = img_scheme.replace("{url}", urls[0]) if urls else ""
            print(f"  🌐  Snap URL:  {proxy_url or '(none)'}")
            if user:
                print(f"  🔑  Creds: {user} / {password}")

            cfg["cameras"][name]["last_live"] = {
                "type":      result_type,
                "proxy_url": proxy_url,
                "user":      user,
                "password":  password,
                "timestamp": datetime.datetime.now().isoformat()[:19],
            }
            save_config(cfg)

            if urls:
                u = urls[0]
                if "/" in u:
                    # REMOTE: "proxy-NN.live.cbs.boschsecurity.com:42090/{hash}"
                    # Port 42090 drops RTSP; use port 443 instead.
                    host_port, hash_path = u.split("/", 1)
                    proxy_host = host_port.split(":")[0]
                    rtsps_url = (
                        f"rtsps://{proxy_host}:443/{hash_path}"
                        f"/rtsp_tunnel?inst={inst}&enableaudio=1&fmtp=1&maxSessionDuration=3600"
                    )
                else:
                    # LOCAL: "192.168.x.x:443" — camera uses TLS with self-signed cert
                    # + Digest auth. FFmpeg can't do RTSPS+Digest with self-signed certs,
                    # so we start a local TCP→TLS proxy and point FFmpeg at plain rtsp://.
                    from urllib.parse import quote as _q
                    cam_host, cam_port = u.split(":")
                    proxy_port = _start_tls_proxy_sync(cam_host, int(cam_port))
                    auth_prefix = f"{_q(user, safe='')}:{_q(password, safe='')}@" if user and password else ""
                    rtsps_url = (
                        f"rtsp://{auth_prefix}127.0.0.1:{proxy_port}"
                        f"/rtsp_tunnel?inst={inst}&enableaudio=1&fmtp=1&maxSessionDuration=3600"
                    )
                    print(f"  🏠  Local stream ({u}) via TLS proxy :{proxy_port}")
                print(f"  📡  RTSPS URL: {rtsps_url}")
                _open_rtsps_stream(rtsps_url, name, proxy_url, use_vlc=getattr(args, "vlc", False))
            else:
                print("  ⚠️   No URLs in response.")
        else:
            print("\n  ❌  Could not open live connection.")

            # Fallback: latest snapshot
            print("\n  📸  Showing latest event snapshot instead...")
            session.headers["Accept"] = "*/*"
            events = api_get_events(session, cam_info["id"], limit=5)
            for ev in events:
                img_url = ev.get("imageUrl")
                if img_url:
                    r = session.get(img_url, timeout=20)
                    if r.status_code == 200:
                        ts   = ev.get("timestamp", "")[:19].replace(":", "-").replace("T", "_")
                        fn   = f"snapshot_{name}_{ts}.jpg"
                        path = os.path.join(BASE_DIR, fn)
                        with open(path, "wb") as f:
                            f.write(r.content)
                        print(f"  💾  {path}  ({len(r.content):,} bytes)")
                        open_file(path)
                        break


def cmd_config(cfg: dict, args) -> None:
    """Show current config (mask the token for security)."""
    display = json.loads(json.dumps(cfg))  # deep copy
    token = display["account"].get("bearer_token", "")
    if token:
        display["account"]["bearer_token"] = f"{token[:20]}...({len(token)} chars)"
    refresh = display["account"].get("refresh_token", "")
    if refresh:
        display["account"]["refresh_token"] = f"{refresh[:20]}...({len(refresh)} chars)"
    print(f"\n── Config: {CONFIG_FILE} ──────────────────────────────────")
    print(json.dumps(display, indent=2))
    print(f"\n  Token age: {check_token_age(cfg)}")


def cmd_info(cfg: dict, args) -> None:
    """Show full camera information from the API.

    Usage:
      python3 bosch_camera.py info           → standard info + stream URLs
      python3 bosch_camera.py info --full    → also fetch 8 extra endpoints
                                               (firmware, motion, audio, light, WiFi, etc.)
    """
    token   = get_token(cfg)
    session = make_session(token)
    full    = getattr(args, "full", False)

    r = session.get(f"{CLOUD_API}/v11/video_inputs", timeout=15)
    if r.status_code == 401:
        print("  ❌  Token expired.")
        return
    r.raise_for_status()
    cameras = r.json()

    print(f"\n── Camera Info ──────────────────────────────────────────────")
    print(f"   Token age: {check_token_age(cfg)}")

    # Protocol version check
    try:
        pr = session.get(
            f"{CLOUD_API}/protocol_support",
            params={"protocol": "11", "client": f"pythonV{VERSION}"},
            timeout=10,
        )
        if pr.status_code == 200:
            pd = pr.json()
            proto_state = pd.get("state", pd.get("status", "UNKNOWN"))
            if proto_state != "SUPPORTED":
                print(f"   ⚠️  Protocol v11 state: {proto_state} — API changes may affect this tool")
            else:
                print(f"   Protocol: v11 ({proto_state})")
        else:
            print(f"   Protocol check: HTTP {pr.status_code}")
    except Exception:
        pass

    print()

    for cam in cameras:
        name   = cam.get("title", cam.get("id"))
        cam_id = cam.get("id", "")
        status = cam.get("connectionStatus", "?")
        if status == "ONLINE":
            icon = "🟢"
        elif status.startswith("UPDATING"):
            icon = "🔄"
        else:
            icon = "🔴"
        model  = cam.get("hardwareVersion", "?")
        fw     = cam.get("firmwareVersion", "?")
        mac    = cam.get("macAddress", "?")
        priv   = cam.get("privacyMode", "?")
        rec    = "✅ ON" if cam.get("recordingOn") else "❌ OFF"
        unread = cam.get("numberOfUnreadEvents", 0)
        tz     = cam.get("timeZone", "?")
        alarm  = cam.get("alarmType") or "NONE"
        notif  = cam.get("notificationsEnabledStatus", "?")

        print(f"  {icon}  {name}")
        print(f"      ID:            {cam_id}")
        model_name = HW_DISPLAY_NAMES.get(model, model)
        print(f"      Model:         {model_name} ({model})   FW: {fw}")
        print(f"      MAC:           {mac}")
        print(f"      Status:        {status}")
        print(f"      Privacy mode:  {priv}")
        print(f"      Recording:     {rec}")
        print(f"      Unread events: {unread}")
        print(f"      Timezone:      {tz}")
        print(f"      Alarm:         {alarm}")
        print(f"      Notifications: {notif}")

        notifs = cam.get("notifications", {})
        notif_parts = [k for k, v in notifs.items() if v]
        if notif_parts:
            print(f"      Notif. types:  {', '.join(notif_parts)}")

        fs = cam.get("featureSupport", {})
        print(f"      Features:      light={fs.get('light')}, sound={fs.get('sound')}, "
              f"viewAngle={fs.get('viewingAngle')}°, panLimit={fs.get('panLimit')}°")

        fst = cam.get("featureStatus", {})
        print(f"      Light sched.:  {fst.get('scheduleStatus')}  "
              f"on={fst.get('generalLightOnTime')} off={fst.get('generalLightOffTime')}")
        print(f"      Light on motion: {fst.get('lightOnMotion')}  "
              f"follow-up={fst.get('lightOnMotionFollowUpTimeSeconds')}s")
        print(f"      Sound recording: {cam.get('soundIsOnForRecording')}")

        # ── WiFi info (always shown if available) ─────────────────────────
        try:
            wr = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/wifiinfo", timeout=10)
            if wr.status_code == 200:
                wd = wr.json()
                ssid   = wd.get("ssid", "?")
                signal = wd.get("signalStrength", wd.get("signal", "?"))
                ip     = wd.get("ipAddress", wd.get("ip", "?"))
                mac_w  = wd.get("macAddress", wd.get("mac", "?"))
                signal_str = f"{signal}%" if isinstance(signal, int) else str(signal)
                print(f"      WiFi:          {ssid}  signal={signal_str}  IP={ip}  MAC={mac_w}")
        except Exception:
            pass

        # ── Streaming URLs (live connection) ──────────────────────────────
        cam_id_local = cam_id
        print(f"      Fetching stream URLs...")
        try:
            sr = session.put(
                f"{CLOUD_API}/v11/video_inputs/{cam_id_local}/connection",
                json={"type": "REMOTE", "highQualityVideo": False},
                headers={"Content-Type": "application/json"},
                timeout=15,
            )
            if sr.status_code == 200:
                sd = sr.json()
                urls = sd.get("urls", [])
                if urls:
                    u = urls[0]
                    proxy_host = u.split(":")[0]
                    hash_path  = u.split("/", 1)[1]
                    snap_url   = sd.get("imageUrlScheme", "https://{url}/snap.jpg").replace("{url}", u)
                    rtsps_url  = (f"rtsps://{proxy_host}:443/{hash_path}"
                                  f"/rtsp_tunnel?inst=2&enableaudio=1&fmtp=1&maxSessionDuration=3600")
                    print(f"      Snap URL:      {snap_url}")
                    print(f"      RTSPS URL:     {rtsps_url}")
                    print(f"      Stream:        H.264 1920×1080 30fps + AAC 16kHz (session ~60s)")
            else:
                print(f"      Stream URLs:   unavailable (HTTP {sr.status_code})")
        except Exception as e:
            print(f"      Stream URLs:   error — {e}")

        # ── Extra endpoints (--full only) ─────────────────────────────────
        if full:
            print(f"\n      ── Full details (--full) ───────────────────────────────")

            # /commissioned
            try:
                cr = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/commissioned", timeout=10)
                if cr.status_code == 200:
                    cd = cr.json()
                    print(f"      Commissioned:  {json.dumps(cd)}")
            except Exception:
                pass

            # /firmware
            try:
                fwr = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/firmware", timeout=10)
                if fwr.status_code == 200:
                    fwd = fwr.json()
                    ver     = fwd.get("version", fwd.get("firmwareVersion", "?"))
                    up2date = fwd.get("upToDate", fwd.get("isUpToDate", "?"))
                    print(f"      Firmware:      version={ver}  upToDate={up2date}")
            except Exception:
                pass

            # /lighting_override
            try:
                lor = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/lighting_override", timeout=10)
                if lor.status_code == 200:
                    lod = lor.json()
                    front = lod.get("frontLightOn", "?")
                    wall  = lod.get("wallwasherOn", "?")
                    print(f"      Light override: frontLightOn={front}  wallwasherOn={wall}")
            except Exception:
                pass

            # /motion
            try:
                mr = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/motion", timeout=10)
                if mr.status_code == 200:
                    md = mr.json()
                    enabled  = md.get("enabled", md.get("motionEnabled", "?"))
                    sens     = md.get("sensitivity", "?")
                    print(f"      Motion:        enabled={enabled}  sensitivity={sens}")
            except Exception:
                pass

            # /audioAlarm
            try:
                ar = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/audioAlarm", timeout=10)
                if ar.status_code == 200:
                    ad = ar.json()
                    enabled   = ad.get("enabled", ad.get("audioAlarmEnabled", "?"))
                    threshold = ad.get("threshold", ad.get("sensitivity", "?"))
                    print(f"      Audio alarm:   enabled={enabled}  threshold={threshold}")
            except Exception:
                pass

            # /recording_options
            try:
                ror = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/recording_options", timeout=10)
                if ror.status_code == 200:
                    rod = ror.json()
                    rec_sound = rod.get("recordSound", rod.get("soundIsOnForRecording", "?"))
                    print(f"      Recording opts: recordSound={rec_sound}")
            except Exception:
                pass

            # /ambient_light_sensor_level
            try:
                alr = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/ambient_light_sensor_level", timeout=10)
                if alr.status_code == 200:
                    ald = alr.json()
                    level = ald.get("ambientLightSensorLevel", ald.get("level", json.dumps(ald)))
                    pct = f" ({round(float(level)*100)}%)" if isinstance(level, (int, float)) else ""
                    print(f"      Ambient light: {level}{pct}")
            except Exception:
                pass

            # /intrusionDetectionConfig (Gen2 only)
            try:
                idr = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/intrusionDetectionConfig", timeout=10)
                if idr.status_code == 200:
                    idd = idr.json()
                    print(f"      Intrusion:     enabled={idd.get('enabled')}, mode={idd.get('detectionMode')}, sensitivity={idd.get('sensitivity')}, distance={idd.get('distance')}m")
            except Exception:
                pass

            # /credentials (local camera userToken)
            try:
                cr = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/credentials", timeout=10)
                if cr.status_code == 200:
                    crd = cr.json()
                    print(f"      Credentials:   userToken={crd.get('userToken', '?')}")
            except Exception:
                pass

            # /rules (camera automation rules)
            try:
                rr = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/rules", timeout=10)
                if rr.status_code == 200:
                    rules = rr.json()
                    print(f"      Rules:         {len(rules)} rule(s) — {json.dumps(rules)[:200]}")
            except Exception:
                pass

            # /timestamp (time/date overlay)
            try:
                tr = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/timestamp", timeout=10)
                if tr.status_code == 200:
                    td = tr.json()
                    print(f"      Timestamp:     overlay={td.get('result', '?')}")
            except Exception:
                pass

            # /privacy_sound_override
            try:
                psr = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/privacy_sound_override", timeout=10)
                if psr.status_code == 200:
                    psd = psr.json()
                    print(f"      Privacy sound: {psd.get('result', '?')}")
                elif psr.status_code == 442:
                    print(f"      Privacy sound: not supported (HTTP 442)")
            except Exception:
                pass

            # ── RCP (via proxy) ───────────────────────────────────────────
            print(f"\n      ── RCP (via proxy) ──────────────────────────────────────")
            try:
                # We already opened a REMOTE connection above for stream URLs.
                # Re-use it by opening a new RCP session on the same proxy hash.
                _rcp_proxy_base, _ = rcp_open_connection(cam_id, token)
                _rcp_sessionid     = rcp_session(_rcp_proxy_base)
                _rcp_url           = f"{_rcp_proxy_base}/rcp.xml"

                # Product name (0x0aea)
                d = rcp_read(_rcp_url, "0x0aea", _rcp_sessionid)
                if d:
                    print(f"      Product:       {rcp_parse_string(d)}")

                # Cloud FQDN (0x0aee)
                d = rcp_read(_rcp_url, "0x0aee", _rcp_sessionid)
                if d:
                    print(f"      Cloud FQDN:    {rcp_parse_string(d)}")

                # Camera clock (0x0a0f)
                d = rcp_read(_rcp_url, "0x0a0f", _rcp_sessionid)
                if d:
                    print(f"      Clock:         {rcp_parse_clock(d)}")

                # LAN IP (0x0a36)
                d = rcp_read(_rcp_url, "0x0a36", _rcp_sessionid)
                if d:
                    ip_str = rcp_parse_ip(d) if len(d) == 4 else rcp_parse_string(d)
                    print(f"      LAN IP:        {ip_str}  (via RCP)")

                # NOTE: privacy cross-check via 0x0d00 was added in v10.2.0
                # and removed in v10.2.1. A/B testing proved 0x0d00 byte[1]
                # stays 1 even with privacy-mode OFF — it's not the mode flag,
                # so the cross-check produced a permanent false-positive.
                # Cloud /v11/video_inputs.privacyMode is the correct source.

            except RuntimeError as _rcp_err:
                print(f"      RCP:           unavailable ({_rcp_err})")
            except Exception as _rcp_ex:
                print(f"      RCP:           error — {_rcp_ex}")

        print()

    # ── Feature flags (account-level, shown with --full) ──────────────
    if full:
        print(f"── Feature Flags ─────────────────────────────────────────────")
        try:
            ffr = session.get(f"{CLOUD_API}/v11/feature_flags", timeout=10)
            if ffr.status_code == 200:
                flags = ffr.json()
                if isinstance(flags, dict):
                    parts = [f"{k}={v}" for k, v in flags.items()]
                    print(f"   {', '.join(parts)}")
                elif isinstance(flags, list):
                    parts = []
                    for flag in flags:
                        if isinstance(flag, dict):
                            fname = flag.get("name", flag.get("key", "?"))
                            fval  = flag.get("value", flag.get("enabled", "?"))
                            parts.append(f"{fname}={fval}")
                        else:
                            parts.append(str(flag))
                    print(f"   {', '.join(parts)}")
                else:
                    print(f"   {json.dumps(flags)}")
            else:
                print(f"   ⚠️  Feature flags: HTTP {ffr.status_code}")
        except Exception:
            pass
        print()


def cmd_privacy(cfg: dict, args) -> None:
    """Get or set privacy mode for a camera via the Bosch cloud API.

    Usage:
      python3 bosch_camera.py privacy [cam-name]        → show current state
      python3 bosch_camera.py privacy [cam-name] on     → turn privacy ON
      python3 bosch_camera.py privacy [cam-name] off    → turn privacy OFF

    API: PUT /v11/video_inputs/{id}/privacy
         Body: {"privacyMode": "ON"/"OFF", "durationInSeconds": null}
         Response: HTTP 204 on success.
    No SHC local API needed — uses cloud API directly.
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cam_arg = getattr(args, "cam", None)
    action  = getattr(args, "action", None)  # "on" / "off" / None

    # If action was parsed as cam and cam_arg looks like an action, swap them
    # (e.g. "privacy on" → cam=None, action="on")
    if cam_arg and cam_arg.lower() in ("on", "off") and action is None:
        action  = cam_arg.lower()
        cam_arg = None

    cams = resolve_cam(cfg, cam_arg)

    # Fetch current state from /v11/video_inputs
    r = session.get(f"{CLOUD_API}/v11/video_inputs", timeout=15)
    if r.status_code == 401:
        print("  ❌  Token expired.")
        return
    r.raise_for_status()
    cam_list = {cam.get("id"): cam for cam in r.json()}

    for name, cam_info in cams.items():
        cam_id  = cam_info["id"]
        cam_raw = cam_list.get(cam_id, {})
        current = cam_raw.get("privacyMode", "UNKNOWN")
        icon    = "🔒" if current.upper() == "ON" else "👁️"

        print(f"\n── Privacy Mode: {name} ─────────────────────────────────────")
        print(f"  {icon}  Current state:  {current}")

        if action is None:
            # Status only
            priv_url = f"{CLOUD_API}/v11/video_inputs/{cam_id}/privacy"
            pr = session.get(priv_url, timeout=10)
            if pr.status_code == 200:
                pd = pr.json()
                dur = pd.get("durationInSeconds")
                end = pd.get("privacyTimeEnd")
                print(f"       Duration:       {dur if dur else 'indefinite'}")
                if end:
                    print(f"       End time:       {end}")
            print(f"\n  Run with 'on' or 'off' to toggle. E.g.:")
            print(f"    python3 bosch_camera.py privacy {name.lower()} on")
            continue

        # Set privacy mode
        new_state = "ON" if action == "on" else "OFF"
        if current.upper() == new_state:
            print(f"  ✅  Already {new_state} — no change needed.")
            continue

        minutes = getattr(args, "minutes", None)
        if new_state == "ON" and minutes:
            body = {"privacyMode": "ON", "privacyTimeSeconds": int(minutes) * 60}
            print(f"  🔄  Setting privacy mode → ON for {minutes} minute(s)...")
        else:
            body = {"privacyMode": new_state, "durationInSeconds": None}
            print(f"  🔄  Setting privacy mode → {new_state}...")

        pr = session.put(
            f"{CLOUD_API}/v11/video_inputs/{cam_id}/privacy",
            json=body,
            headers={"Content-Type": "application/json"},
            timeout=10,
        )
        if pr.status_code in (200, 201, 204):
            icon_new = "🔒" if new_state == "ON" else "👁️"
            print(f"  {icon_new}  Privacy mode set to {new_state}.")
            if new_state == "ON":
                if minutes:
                    print(f"     Camera is now blocked for {minutes} minute(s).")
                else:
                    print("     Camera is now blocked — no live images available.")
            else:
                print("     Camera is now active — live images available.")
        else:
            print(f"  ❌  Failed: HTTP {pr.status_code}  {pr.text[:200]}")


def cmd_light(cfg: dict, args) -> None:
    """Get or set the camera light (manual override) via the Bosch cloud API.

    Usage:
      python3 bosch_camera.py light [cam-name]        → show current state
      python3 bosch_camera.py light [cam-name] on     → turn light ON
      python3 bosch_camera.py light [cam-name] off    → turn light OFF

    API: PUT /v11/video_inputs/{id}/lighting_override
         ON:  {"frontLightOn": true, "wallwasherOn": true, "frontLightIntensity": 1.0}
         OFF: {"frontLightOn": false, "wallwasherOn": false}
         Response: HTTP 204 on success.
    Only available for cameras with featureSupport.light = true (outdoor camera).

    Extended syntax:
      light [cam] front on/off      → toggle front light only
      light [cam] wall on/off       → toggle wallwasher only
      light [cam] intensity <0-100> → set front light brightness

    featureStatus fields (shown in status view):
      scheduleStatus         — ALWAYS_OFF / ALWAYS_ON / SCHEDULE
      frontIlluminatorInGeneralLightOn  — general light mode enabled
      lightOnMotion          — activate light on motion detection
      lightOnMotionFollowUpTimeSeconds  — how long after motion
      generalLightOnTime / generalLightOffTime  — schedule window
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cam_arg = getattr(args, "cam", None)
    action  = getattr(args, "action", None)

    # Allow "light on" / "light off" without camera name
    if cam_arg and cam_arg.lower() in ("on", "off") and action is None:
        action  = cam_arg.lower()
        cam_arg = None
    # Allow "light front on" / "light wall off" / "light intensity 50"
    if cam_arg and cam_arg.lower() in ("front", "wall", "intensity"):
        component = cam_arg.lower()
        cam_arg = None
        action = f"{component} {action}" if action else component
    elif action and action.lower() in ("front", "wall", "intensity"):
        extra = getattr(args, "extra_args", [])
        action = f"{action.lower()} {extra[0]}" if extra else action.lower()

    cams = resolve_cam(cfg, cam_arg)

    r = session.get(f"{CLOUD_API}/v11/video_inputs", timeout=15)
    if r.status_code == 401:
        print("  ❌  Token expired.")
        return
    r.raise_for_status()
    cam_list = {cam.get("id"): cam for cam in r.json()}

    for name, cam_info in cams.items():
        cam_id  = cam_info["id"]
        cam_raw = cam_list.get(cam_id, {})
        feat_support = cam_raw.get("featureSupport", {})
        has_light    = feat_support.get("light", False)
        feat_status  = cam_raw.get("featureStatus", {})

        print(f"\n── Camera Light: {name} ─────────────────────────────────────")
        if not has_light:
            print(f"  ℹ️   This camera does not support a built-in light.")
            continue

        sched     = feat_status.get("scheduleStatus", "UNKNOWN")
        front_on  = feat_status.get("frontIlluminatorInGeneralLightOn", False)
        intensity = feat_status.get("frontIlluminatorGeneralLightIntensity", 0)
        wall_on   = feat_status.get("wallwasherInGeneralLightOn", False)
        on_time   = feat_status.get("generalLightOnTime", "?")
        off_time  = feat_status.get("generalLightOffTime", "?")
        on_motion = feat_status.get("lightOnMotion", False)
        follow_up = feat_status.get("lightOnMotionFollowUpTimeSeconds", 0)

        mode_icon = {"ALWAYS_ON": "💡", "ALWAYS_OFF": "🌑", "SCHEDULE": "📅"}.get(sched, "❓")
        print(f"  {mode_icon}  Schedule mode:       {sched}")
        print(f"  {'💡' if front_on else '🌑'}  General light mode:  {'ON' if front_on else 'OFF'}  "
              f"(intensity: {intensity:.0%})")
        if wall_on:
            print(f"  💡  Wallwasher:          ON")
        print(f"  🕐  Schedule window:     {on_time} → {off_time}")
        print(f"  🏃  Light on motion:     {'YES' if on_motion else 'NO'}  "
              f"(follow-up: {follow_up}s)")

        # Also show current override state
        try:
            ovr = session.get(
                f"{CLOUD_API}/v11/video_inputs/{cam_id}/lighting_override",
                timeout=10,
            ).json()
            ovr_front = ovr.get("frontLightOn", False)
            ovr_wall  = ovr.get("wallwasherOn", False)
            ovr_int   = ovr.get("frontLightIntensity")
            print(f"  ── Override (instant) ──")
            print(f"  {'💡' if ovr_front else '🌑'}  Front light:         {'ON' if ovr_front else 'OFF'}"
                  + (f"  (intensity: {ovr_int:.0%})" if ovr_int is not None else ""))
            print(f"  {'💡' if ovr_wall else '🌑'}  Wallwasher:          {'ON' if ovr_wall else 'OFF'}")
        except Exception:
            pass

        if action is None:
            print()
            print(f"  Commands:")
            print(f"    light {name.lower()} on              # both lights ON 100%")
            print(f"    light {name.lower()} off             # both lights OFF")
            print(f"    light {name.lower()} front on/off    # front light only")
            print(f"    light {name.lower()} wall on/off     # wallwasher only")
            print(f"    light {name.lower()} intensity 50    # front light 50%")
            continue

        # Read current override state to preserve components
        try:
            cur = session.get(
                f"{CLOUD_API}/v11/video_inputs/{cam_id}/lighting_override",
                timeout=10,
            ).json()
        except Exception:
            cur = {}
        cur_front = cur.get("frontLightOn", False)
        cur_wall  = cur.get("wallwasherOn", False)
        cur_int   = cur.get("frontLightIntensity") or 1.0

        # Parse action: "on", "off", "front on", "wall off", "intensity 50"
        parts = action.split()
        if parts[0] in ("front", "wall", "intensity") and len(parts) >= 2:
            component = parts[0]
            val = parts[1]
            if component == "front":
                cur_front = val.lower() == "on"
                desc = f"front light → {'ON' if cur_front else 'OFF'}"
            elif component == "wall":
                cur_wall = val.lower() == "on"
                desc = f"wallwasher → {'ON' if cur_wall else 'OFF'}"
            elif component == "intensity":
                cur_int = max(0.0, min(1.0, int(val) / 100))
                cur_front = True  # intensity implies front on
                desc = f"front light intensity → {int(cur_int * 100)}%"
        elif action == "on":
            cur_front = True
            cur_wall = True
            cur_int = 1.0
            desc = "all lights → ON"
        else:
            cur_front = False
            cur_wall = False
            desc = "all lights → OFF"

        body = {
            "frontLightOn": cur_front,
            "wallwasherOn": cur_wall,
            "frontLightIntensity": cur_int,
        }

        print(f"\n  🔄  Setting light override: {desc}...")
        pr = session.put(
            f"{CLOUD_API}/v11/video_inputs/{cam_id}/lighting_override",
            json=body,
            headers={"Content-Type": "application/json"},
            timeout=10,
        )
        if pr.status_code in (200, 201, 204):
            print(f"  💡  Done. Front={'ON' if cur_front else 'OFF'}  "
                  f"Wall={'ON' if cur_wall else 'OFF'}  "
                  f"Intensity={int(cur_int * 100)}%")
        else:
            print(f"  ❌  Failed: HTTP {pr.status_code}  {pr.text[:200]}")


def cmd_pan(cfg: dict, args) -> None:
    """Get or set the pan position of the 360 camera via the Bosch cloud API.

    Usage:
      python3 bosch_camera.py pan [cam-name]           → show current position
      python3 bosch_camera.py pan [cam-name] left      → pan to -120° (full left)
      python3 bosch_camera.py pan [cam-name] center    → pan to 0° (center)
      python3 bosch_camera.py pan [cam-name] right     → pan to +120° (full right)
      python3 bosch_camera.py pan [cam-name] <-120..120>  → pan to absolute position

    API: GET /v11/video_inputs/{id}/pan
           → {"currentAbsolutePosition": 15, "panLimit": 120}
         PUT /v11/video_inputs/{id}/pan
           Body: {"absolutePosition": -120}   (range: -panLimit to +panLimit)
           Response: {"currentAbsolutePosition": -120, "cameraStoppedAtLimit": false,
                      "estimatedTimeToCompletion": 970}
    Only available for cameras with featureSupport.panLimit > 0 (indoor 360 camera).
    Discovered 2026-03-21 via mitmproxy capture.
    """
    token   = get_token(cfg)
    session = make_session(token)
    cam_arg = getattr(args, "cam", None)
    action  = getattr(args, "action", None)

    # Allow "pan left" / "pan center" / "pan right" / "pan 45" without camera name
    PRESETS = ("left", "center", "right")
    if cam_arg and action is None:
        try:
            int(cam_arg)
            action, cam_arg = cam_arg, None   # "pan 45" → action=45, cam=None
        except ValueError:
            if cam_arg.lower() in PRESETS:
                action, cam_arg = cam_arg.lower(), None

    cams = resolve_cam(cfg, cam_arg)

    r = session.get(f"{CLOUD_API}/v11/video_inputs", timeout=15)
    if r.status_code == 401:
        print("  ❌  Token expired.")
        return
    r.raise_for_status()
    cam_list = {cam.get("id"): cam for cam in r.json()}

    for name, cam_info in cams.items():
        cam_id      = cam_info["id"]
        cam_raw     = cam_list.get(cam_id, {})
        pan_limit   = cam_raw.get("featureSupport", {}).get("panLimit", 0)

        print(f"\n── Pan Control: {name} ──────────────────────────────────────")
        if not pan_limit:
            print(f"  ℹ️   This camera does not support pan (panLimit=0).")
            continue

        # Fetch current position
        pr = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/pan", timeout=10)
        if pr.status_code != 200:
            print(f"  ❌  Could not fetch pan state: HTTP {pr.status_code}")
            continue
        pan_data = pr.json()
        current  = pan_data.get("currentAbsolutePosition", 0)
        limit    = pan_data.get("panLimit", pan_limit)

        # Visual position bar
        pct   = (current + limit) / (2 * limit)  # 0.0 = full left, 1.0 = full right
        width = 30
        pos   = int(pct * width)
        bar   = "─" * pos + "●" + "─" * (width - pos)
        direction = "CENTER" if abs(current) < 5 else ("RIGHT ▶" if current > 0 else "◀ LEFT")
        print(f"  📍  Position:  {current:+4d}°  {direction}")
        print(f"      Range:    -{limit}° ◀ [{bar}] ▶ +{limit}°")

        if action is None:
            print(f"\n  Run with 'left', 'center', 'right', or a number (-{limit}..+{limit}). E.g.:")
            print(f"    python3 bosch_camera.py pan {name.lower()} center")
            print(f"    python3 bosch_camera.py pan {name.lower()} 45")
            continue

        # Resolve target position
        PRESET_MAP = {"left": -limit, "center": 0, "right": limit}
        if action.lower() in PRESET_MAP:
            target = PRESET_MAP[action.lower()]
        else:
            try:
                target = int(action)
            except ValueError:
                print(f"  ❌  Unknown action '{action}'. Use left/center/right or a number.")
                continue
            if not (-limit <= target <= limit):
                print(f"  ❌  Position {target} out of range (-{limit} to +{limit}).")
                continue

        if target == current:
            print(f"  ✅  Already at {target:+d}° — no change needed.")
            continue

        direction_str = "▶ right" if target > current else "◀ left"
        print(f"\n  🔄  Panning {direction_str} → {target:+d}°...")
        resp = session.put(
            f"{CLOUD_API}/v11/video_inputs/{cam_id}/pan",
            json={"absolutePosition": target},
            headers={"Content-Type": "application/json"},
            timeout=10,
        )
        if resp.status_code == 200:
            data = resp.json()
            new_pos = data.get("currentAbsolutePosition", target)
            eta_ms  = data.get("estimatedTimeToCompletion", 0)
            at_limit = data.get("cameraStoppedAtLimit", False)
            print(f"  ✅  Moving to {new_pos:+d}°  (ETA: {eta_ms}ms)")
            if at_limit:
                print(f"  ⚠️   Camera stopped at mechanical limit.")
        else:
            print(f"  ❌  Failed: HTTP {resp.status_code}  {resp.text[:200]}")


def cmd_notifications(cfg: dict, args) -> None:
    """Get or set notification settings for a camera via the Bosch cloud API.

    Usage:
      python3 bosch_camera.py notifications [cam-name]        → show current state
      python3 bosch_camera.py notifications [cam-name] on     → enable (FOLLOW_CAMERA_SCHEDULE)
      python3 bosch_camera.py notifications [cam-name] off    → disable (ALWAYS_OFF)

    API: PUT /v11/video_inputs/{id}/enable_notifications
         Body: {"enabledNotificationsStatus": "FOLLOW_CAMERA_SCHEDULE"/"ALWAYS_OFF"}
         Response: HTTP 204 on success.
    State is visible in GET /v11/video_inputs as notificationsEnabledStatus.
    """
    token   = get_token(cfg)
    session = make_session(token)
    cam_arg = getattr(args, "cam", None)
    action  = getattr(args, "action", None)

    if cam_arg and cam_arg.lower() in ("on", "off") and action is None:
        action  = cam_arg.lower()
        cam_arg = None

    cams = resolve_cam(cfg, cam_arg)

    r = session.get(f"{CLOUD_API}/v11/video_inputs", timeout=15)
    if r.status_code == 401:
        print("  ❌  Token expired.")
        return
    r.raise_for_status()
    cam_list = {cam.get("id"): cam for cam in r.json()}

    for name, cam_info in cams.items():
        cam_id  = cam_info["id"]
        cam_raw = cam_list.get(cam_id, {})
        current = cam_raw.get("notificationsEnabledStatus", "UNKNOWN")
        notif_on = current != "ALWAYS_OFF"
        icon     = "🔔" if notif_on else "🔕"

        # Friendly display for all known states
        STATE_LABELS = {
            "ALWAYS_OFF":             "OFF",
            "FOLLOW_CAMERA_SCHEDULE": "ON (follows schedule)",
            "ON_CAMERA_SCHEDULE":     "ON (explicit schedule)",
        }
        state_label = STATE_LABELS.get(current, current)

        print(f"\n── Notifications: {name} ─────────────────────────────────────")
        print(f"  {icon}  Current state:  {current}  →  {state_label}")

        if action is None:
            print(f"\n  Run with 'on' or 'off' to toggle. E.g.:")
            print(f"    python3 bosch_camera.py notifications {name.lower()} on")
            continue

        new_status = "FOLLOW_CAMERA_SCHEDULE" if action == "on" else "ALWAYS_OFF"
        # ON_CAMERA_SCHEDULE also counts as "on" — don't overwrite with FOLLOW_CAMERA_SCHEDULE
        already_on  = action == "on"  and current in ("FOLLOW_CAMERA_SCHEDULE", "ON_CAMERA_SCHEDULE")
        already_off = action == "off" and current == "ALWAYS_OFF"
        if already_on or already_off:
            print(f"  ✅  Already {current} — no change needed.")
            continue

        print(f"  🔄  Setting notifications → {new_status}...")
        pr = session.put(
            f"{CLOUD_API}/v11/video_inputs/{cam_id}/enable_notifications",
            json={"enabledNotificationsStatus": new_status},
            headers={"Content-Type": "application/json"},
            timeout=10,
        )
        if pr.status_code in (200, 201, 204):
            icon_new = "🔔" if action == "on" else "🔕"
            print(f"  {icon_new}  Notifications set to {new_status}.")
        else:
            print(f"  ❌  Failed: HTTP {pr.status_code}  {pr.text[:200]}")


# ── FCM Push constants (from APK analysis) ───────────────────────────────────
FCM_PROJECT_ID    = "bosch-smart-cameras"
FCM_APP_ID        = "1:404630424405:android:9e5b6b58e4c70075"
FCM_SENDER_ID     = "404630424405"

# iOS FCM config (from iOS app v2.11.2 analysis)
FCM_IOS_APP_ID    = "1:404630424405:ios:715aae2570e39faad9bddc"

def _get_fcm_ios_api_key() -> str:
    """Return the Firebase API key for the iOS Bosch Smart Camera app."""
    import base64
    return base64.b64decode("QUl6YVN5QmxyN1o0ZmpaM0lmcnhsN1VRZFE4eGZRd3g5WFJBYnBJ").decode()

def _get_fcm_api_key() -> str:
    """Return the Google API key for FCM registration.

    Switched 2026-04-20 to the official OSS key provided by Bosch (Sebastian Raff).
    Firebase Installations + FCM registration permissions confirmed working.
    """
    import base64
    return base64.b64decode("QUl6YVN5Q0toaGZ4ZlRzMUc3V3Z6VERBaU8wQWlzN0VIMjVEYk9z").decode()
FCM_CRED_KEY      = "_fcm_credentials"  # key in bosch_config.json settings


def _send_signal_alert(
    signal_url: str, sender: str, recipients: list[str],
    cam_name: str, event_type: str, ts: str,
    image_url: str = "", token: str = "",
) -> None:
    """Send an alert message (with optional snapshot) via signal-cli-rest-api.

    API: POST {signal_url}/v2/send
    Body: {"message": "...", "number": sender, "recipients": [...], "base64_attachments": [...]}
    """
    import base64 as _b64

    msg = f"{cam_name}: {event_type} um {ts}"
    body: dict = {
        "message": msg,
        "number": sender,
        "recipients": recipients,
    }

    # Download and attach the event snapshot if available
    if image_url and token:
        try:
            headers = {"Authorization": f"Bearer {token}", "Accept": "*/*"}
            r = requests.get(image_url, headers=headers, timeout=15)
            if r.status_code == 200 and "image" in r.headers.get("Content-Type", ""):
                b64 = _b64.b64encode(r.content).decode()
                body["base64_attachments"] = [b64]
        except Exception as e:
            print(f"             ⚠️  Signal image download failed: {e}")

    try:
        r = requests.post(
            f"{signal_url.rstrip('/')}/v2/send",
            json=body, timeout=15,
        )
        if r.status_code in (200, 201):
            print(f"             📨 Signal alert sent to {', '.join(recipients)}")
        else:
            print(f"             ⚠️  Signal send failed: HTTP {r.status_code} {r.text[:100]}")
    except Exception as e:
        print(f"             ⚠️  Signal send error: {e}")


def _watch_fcm_push(cfg: dict, token: str, cams: dict, duration: int, auto_snap: bool,
                    signal_url: str = "", signal_sender: str = "", signal_recipients: list[str] | None = None,
                    fcm_app_id: str = "", fcm_api_key: str = "", mode_label: str = "Android") -> None:
    """Watch for events using FCM push notifications instead of polling.

    Near-instant event detection (~2-3s) via Firebase Cloud Messaging.
    Requires: pip install firebase-messaging
    """
    try:
        import asyncio
        from firebase_messaging import FcmPushClient, FcmRegisterConfig
    except ImportError:
        print("  ❌  firebase-messaging not installed. Install with:")
        print("      pip3 install firebase-messaging")
        return

    session_req = make_session(token)
    cam_ids = {name: info["id"] for name, info in cams.items()}

    # Build baseline
    last_seen: dict[str, str] = {}
    print(f"\n  Fetching baseline events...")
    for name, cam_info in cams.items():
        events = api_get_events(session_req, cam_info["id"], limit=1)
        if events:
            last_seen[name] = events[0].get("id", "")
        print(f"  {name}: baseline = {last_seen.get(name, '(none)')[:8]}")

    total_new = [0]
    start_time = [time.time()]

    def on_notification(notification, persistent_id, obj=None):
        """Called on each FCM push — fetch events for all cameras."""
        now_str = datetime.datetime.now().strftime("%H:%M:%S")
        # Re-get token in case it was refreshed. make_session() returns the
        # cached module-level Session with the Authorization header updated, so
        # the connection pool is shared across all FCM-triggered fetches.
        tok = cfg["account"].get("bearer_token", token)
        # Pre-emptive token refresh before making API calls.
        if _is_token_near_expiry(tok):
            tok = get_token(cfg)
        sess = make_session(tok)

        for name, cam_id in cam_ids.items():
            try:
                events = api_get_events(sess, cam_id, limit=5)
            except Exception:
                events = []
            if not events:
                continue

            baseline = last_seen.get(name, "")
            new_events = []
            for ev in events:
                if ev.get("id", "") == baseline:
                    break
                new_events.append(ev)

            for ev in reversed(new_events):
                etype   = ev.get("eventType", "EVENT")
                ts      = ev.get("timestamp", "")[:19]
                img_url = ev.get("imageUrl", "")
                clip_url = ev.get("videoClipUrl", "")
                icon    = "🔊" if "AUDIO" in etype else ("👤" if etype == "PERSON" else "🚨")
                print(f"\n  [{now_str}] {icon} {etype:<15s}  cam={name:<12s}  {ts}  (via FCM push)")
                if img_url:
                    print(f"             📸 {img_url}")
                if clip_url:
                    print(f"             🎬 {clip_url}")
                total_new[0] += 1

                # Signal alert
                if signal_url and signal_sender and signal_recipients:
                    _send_signal_alert(
                        signal_url, signal_sender, signal_recipients,
                        name, etype, ts, img_url, tok,
                    )

                if auto_snap and img_url:
                    try:
                        r = sess.get(img_url, timeout=15)
                        if r.status_code == 200 and "image" in r.headers.get("Content-Type", ""):
                            fname = f"event_{name}_{ts.replace(':', '-')}.jpg"
                            fpath = os.path.join(BASE_DIR, fname)
                            with open(fpath, "wb") as f:
                                f.write(r.content)
                            print(f"             💾 Saved: {fpath}")
                            open_file(fpath)
                    except Exception as e:
                        print(f"             ⚠️  Snapshot error: {e}")

            if new_events:
                last_seen[name] = new_events[0].get("id", baseline)
                # Mark new events as read on the Bosch cloud
                read_ids = [ev.get("id") for ev in new_events if ev.get("id")]
                if read_ids:
                    try:
                        api_mark_events_read(sess, read_ids)
                    except Exception:
                        pass

    def on_creds_updated(creds):
        cfg["settings"][FCM_CRED_KEY] = creds
        save_config(cfg)

    async def _run():
        fcm_config = FcmRegisterConfig(
            project_id=FCM_PROJECT_ID,
            app_id=fcm_app_id or FCM_APP_ID,
            api_key=fcm_api_key or _get_fcm_api_key(),
            messaging_sender_id=FCM_SENDER_ID,
        )

        saved_creds = cfg.get("settings", {}).get(FCM_CRED_KEY)

        client = FcmPushClient(
            callback=on_notification,
            fcm_config=fcm_config,
            credentials=saved_creds,
            credentials_updated_callback=on_creds_updated,
        )

        print(f"\n  🔑  Registering with FCM...")
        fcm_token = await client.checkin_or_register()
        print(f"  ✅  FCM Token: {fcm_token[:50]}...")

        # Register with Bosch CBS — deviceType must match FCM platform
        device_type = "IOS" if "ios:" in (fcm_app_id or "") else "ANDROID"
        print(f"  🔗  Registering with Bosch CBS (deviceType={device_type})...")
        headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
        r = requests.post(
            f"{CLOUD_API}/v11/devices",
            headers=headers,
            json={"deviceType": device_type, "deviceToken": fcm_token},
            timeout=10,
        )
        if r.status_code in (200, 201, 204):
            print(f"  ✅  Registered with Bosch CBS!")
        else:
            print(f"  ⚠️   CBS registration: HTTP {r.status_code} — pushes may not arrive")

        n_cams = len(cams)
        print(f"\n  📡  Listening for FCM pushes ({n_cams} camera(s), mode={mode_label})...")
        print(f"      Near-instant event detection (~2-3s latency)")
        if duration:
            print(f"      Will stop after {duration}s.")
        print(f"      Press Ctrl+C to stop.\n")

        start_time[0] = time.time()

        await client.start()

        try:
            while not _STOP_REQUESTED.is_set():
                await asyncio.sleep(1)
                if duration and (time.time() - start_time[0]) >= duration:
                    print(f"\n  Duration of {duration}s reached — stopping.")
                    break
        except asyncio.CancelledError:
            pass
        finally:
            # Ensure FCM client is always shut down cleanly, even on SIGTERM.
            try:
                await client.stop()
            except Exception as e:
                print(f"  [warn] FCM client.stop() raised: {e}", file=sys.stderr)

    _install_stop_handlers()

    try:
        import asyncio
        asyncio.run(_run())
    except KeyboardInterrupt:
        elapsed = int(time.time() - start_time[0])
        print(f"\n\n  Stopped after {elapsed}s. Total new events: {total_new[0]}")


def cmd_watch(cfg: dict, args) -> None:
    """
    Watch for new camera events by polling GET /v11/events every N seconds.

    Usage:
      python3 bosch_camera.py watch [<cam-name>] [--interval N] [--duration N]

    Polls every --interval seconds (default 30). Runs until Ctrl+C or --duration
    seconds elapsed. Prints each new event with type, timestamp, image URL and
    clip URL.
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cams    = resolve_cam(cfg, getattr(args, "cam", None))
    interval  = getattr(args, "interval", 30) or 30
    duration  = getattr(args, "duration", 0) or 0
    auto_snap = getattr(args, "snapshot", False)
    use_push  = getattr(args, "push", False)
    signal_url = getattr(args, "signal", "") or ""
    signal_sender = getattr(args, "signal_sender", "") or ""
    signal_recipients_str = getattr(args, "signal_recipients", "") or ""
    signal_recipients = [r.strip() for r in signal_recipients_str.split(",") if r.strip()] if signal_recipients_str else []

    if signal_url:
        print(f"  📨  Signal alerts → {signal_url} (sender={signal_sender}, recipients={signal_recipients})")

    push_mode = getattr(args, "push_mode", "auto")

    if use_push:
        push_succeeded = False

        modes_to_try = []
        if push_mode == "ios":
            modes_to_try = [("iOS", FCM_IOS_APP_ID, _get_fcm_ios_api_key)]
        elif push_mode == "android":
            modes_to_try = [("Android", FCM_APP_ID, _get_fcm_api_key)]
        elif push_mode == "polling":
            modes_to_try = []  # skip FCM, go straight to polling
        else:  # auto: ios → android
            modes_to_try = [
                ("iOS", FCM_IOS_APP_ID, _get_fcm_ios_api_key),
                ("Android", FCM_APP_ID, _get_fcm_api_key),
            ]

        for label, app_id, key_fn in modes_to_try:
            try:
                if len(modes_to_try) > 1:
                    print(f"\n  🔄  Auto mode: trying {label} FCM...")
                _watch_fcm_push(cfg, token, cams, duration, auto_snap,
                                signal_url, signal_sender, signal_recipients,
                                fcm_app_id=app_id, fcm_api_key=key_fn(),
                                mode_label=label)
                push_succeeded = True
                break
            except Exception as e:
                print(f"\n  ⚠️  {label} FCM failed: {e}")

        if push_succeeded:
            return

        if push_mode != "polling":
            print(f"  🔄  All FCM modes failed — falling back to standard API polling...")
        # Fall through to polling code below

    # Build initial baseline of seen event IDs per camera
    last_seen: dict[str, str] = {}
    print(f"\n  Fetching baseline events...")
    for name, cam_info in cams.items():
        events = api_get_events(session, cam_info["id"], limit=1)
        if events:
            last_seen[name] = events[0].get("id", "")
        else:
            last_seen[name] = ""
        print(f"  {name}: baseline event id = {last_seen[name] or '(none)'}")

    n_cams = len(cams)
    print(f"\nWatching {n_cams} camera(s)... (Ctrl+C to stop)")
    if duration:
        print(f"  Will stop after {duration}s.")
    print(f"  Polling every {interval}s.")
    if auto_snap:
        print(f"  --snapshot: will auto-download and open event JPEG on new events.")
    print()

    start_time = time.time()
    total_new  = 0

    def _renew_session() -> tuple[str, requests.Session]:
        # With cached module-level session, this only refreshes the Bearer token
        # on the shared Session object — no new connection pool is created.
        t = get_token(cfg)
        s = make_session(t)
        return t, s

    _install_stop_handlers()

    try:
        while not _STOP_REQUESTED.is_set():
            if duration and (time.time() - start_time) >= duration:
                print(f"\n  Duration of {duration}s reached — stopping.")
                break

            # Sleep in short slices so SIGTERM/SIGINT is honored promptly.
            slept = 0.0
            while slept < interval and not _STOP_REQUESTED.is_set():
                time.sleep(min(1.0, interval - slept))
                slept += 1.0
            if _STOP_REQUESTED.is_set():
                break

            now_str = datetime.datetime.now().strftime("%H:%M:%S")

            # Pre-emptive token refresh: renew before the token expires
            # rather than waiting for a 401 response.
            if _is_token_near_expiry(token):
                token, session = _renew_session()

            for name, cam_info in cams.items():
                cam_id  = cam_info["id"]

                # Fetch latest events; retry once on 401
                try:
                    events = api_get_events(session, cam_id, limit=20)
                except Exception as e:
                    print(f"  [warn] event fetch failed for {name}: {e}",
                          file=sys.stderr)
                    events = []

                if not events and session.headers.get("Authorization", ""):
                    # Possibly 401 — try renewing
                    try:
                        token, session = _renew_session()
                        events = api_get_events(session, cam_id, limit=20)
                    except Exception as e:
                        print(f"  [warn] event re-fetch after renew failed for {name}: {e}",
                              file=sys.stderr)
                        events = []

                baseline = last_seen.get(name, "")
                new_events = []
                for ev in events:
                    ev_id = ev.get("id", "")
                    if ev_id == baseline:
                        break
                    new_events.append(ev)

                # Print new events (oldest first — events list is newest-first)
                for ev in reversed(new_events):
                    etype     = ev.get("eventType", "EVENT")
                    ts        = ev.get("timestamp", "")[:19]
                    img_url   = ev.get("imageUrl", "")
                    clip_url  = ev.get("videoClipUrl", "")
                    type_icon = "🔊" if "AUDIO" in etype else ("👤" if etype == "PERSON" else "🚨")
                    print(f"  [{now_str}] {type_icon} {etype:<15s}  cam={name:<12s}  {ts}")
                    if img_url:
                        print(f"             📸 {img_url}")
                    if clip_url:
                        print(f"             🎬 {clip_url}")
                    total_new += 1
                    # Signal alert
                    if signal_url and signal_sender and signal_recipients:
                        _send_signal_alert(
                            signal_url, signal_sender, signal_recipients,
                            name, etype, ts, img_url, token,
                        )
                    # Auto-download and open the event snapshot if requested
                    if auto_snap and img_url:
                        try:
                            r = session.get(img_url, timeout=15)
                            if r.status_code == 200 and "image" in r.headers.get("Content-Type", ""):
                                fname = f"event_{name}_{ts.replace(':', '-').replace(' ', '_')}.jpg"
                                fpath = os.path.join(BASE_DIR, fname)
                                with open(fpath, "wb") as f:
                                    f.write(r.content)
                                print(f"             💾 Saved: {fpath}")
                                open_file(fpath)
                            else:
                                print(f"             ⚠️  Could not download snapshot (HTTP {r.status_code})")
                        except Exception as snap_err:
                            print(f"             ⚠️  Snapshot download error: {snap_err}")

                if new_events:
                    last_seen[name] = new_events[0].get("id", baseline)
                    # Mark new events as read on the Bosch cloud
                    read_ids = [ev.get("id") for ev in new_events if ev.get("id")]
                    if read_ids:
                        try:
                            api_mark_events_read(session, read_ids)
                        except Exception:
                            pass

    except KeyboardInterrupt:
        elapsed = int(time.time() - start_time)
        print(f"\n\n  Stopped after {elapsed}s. Total new events seen: {total_new}")


def cmd_intercom(cfg: dict, args) -> None:
    """
    Open a two-way audio (intercom) session to a camera.

    Usage:
      python3 bosch_camera.py intercom <cam-name> [--duration N] [--speaker-level N]

    Opens a media tunnel to the camera for push-to-talk audio.
    Requires: pip install pyaudio

    API flow:
      1. PUT /v11/video_inputs/{id}/connection -> get proxy URL
      2. Open TCP+TLS socket to proxy for bidirectional audio
      3. Capture microphone -> send to camera speaker
      4. Camera audio -> play on local speakers
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cams    = resolve_cam(cfg, getattr(args, "cam", None))
    duration = getattr(args, "duration", 60) or 60
    speaker_level = getattr(args, "speaker_level", 50) or 50

    if len(cams) != 1:
        print("  ❌  Intercom requires exactly one camera. Specify the camera name.")
        return

    cam_name, cam_info = next(iter(cams.items()))
    cam_id = cam_info["id"]

    print(f"\n── Intercom: {cam_name} ──────────────────────────────────────")

    # Step 1: Set speaker level
    print(f"  🔊  Setting speaker level to {speaker_level}%...")
    r = session.put(
        f"{CLOUD_API}/v11/video_inputs/{cam_id}/audio",
        json={"audioEnabled": True, "SpeakerLevel": speaker_level},
        timeout=10,
    )
    if r.status_code in (200, 201, 204):
        print(f"  ✅  Speaker level set to {speaker_level}%")
    elif r.status_code == 442:
        print(f"  ⚠️  Audio settings not supported on this camera model (HTTP 442)")
    else:
        print(f"  ⚠️  Could not set speaker level: HTTP {r.status_code}")

    # Step 2: Open live connection with audio enabled
    print(f"  📡  Opening live connection with audio...")
    conn_data = None
    for conn_type in LIVE_TYPE_CANDIDATES:
        try:
            r = session.put(
                f"{CLOUD_API}/v11/video_inputs/{cam_id}/connection",
                json={"type": conn_type, "highQualityVideo": False},
                timeout=10,
            )
            if r.status_code in (200, 201):
                conn_data = r.json()
                break
        except Exception:
            continue

    if not conn_data or not conn_data.get("urls"):
        print(f"  ❌  Could not open live connection for intercom.")
        return

    proxy_url = conn_data["urls"][0]
    proxy_host = proxy_url.split("/")[0].replace(":42090", "")
    proxy_hash = proxy_url.split("/", 1)[1] if "/" in proxy_url else ""

    # Build RTSPS URL with audio enabled
    rtsps_url = f"rtsps://{proxy_host}:443/{proxy_hash}/rtsp_tunnel?inst=2&enableaudio=1&fmtp=1&maxSessionDuration={duration}"

    print(f"  ✅  Connection established!")
    print(f"  🎤  Intercom session ({duration}s)")
    print(f"  🔗  Audio stream: {rtsps_url}")
    print()

    # Step 3: Use ffmpeg for bidirectional audio
    # Listen: RTSPS stream -> local speakers
    # Talk: local microphone -> not yet supported via cloud API (requires media tunnel)
    print(f"  📻  Starting audio playback from camera...")
    print(f"      (Two-way talk requires direct media tunnel — listen-only via RTSPS)")
    print(f"      Press Ctrl+C to stop.\n")

    # Use ffplay for audio playback
    ffplay = shutil.which("ffplay")
    if not ffplay:
        print(f"  ❌  ffplay not found. Install ffmpeg to use intercom.")
        print(f"      brew install ffmpeg")
        return

    try:
        proc = subprocess.Popen(
            [
                ffplay,
                "-nodisp",           # no video window
                "-rtsp_transport", "tcp",
                "-fflags", "nobuffer",
                "-flags", "low_delay",
                "-analyzeduration", "500000",
                "-probesize", "32768",
                rtsps_url,
            ],
            stdout=subprocess.DEVNULL,
            stderr=subprocess.DEVNULL,
        )
        print(f"  🔊  Playing camera audio (PID {proc.pid})...")
        print(f"      Ctrl+C to stop.")
        proc.wait(timeout=duration)
    except subprocess.TimeoutExpired:
        proc.terminate()
        print(f"\n  ⏱️  Duration of {duration}s reached.")
    except KeyboardInterrupt:
        proc.terminate()
        print(f"\n  ⏹️  Intercom stopped.")
    except Exception as e:
        print(f"  ❌  Intercom error: {e}")


def cmd_motion(cfg: dict, args) -> None:
    """
    Get or set motion detection settings.

    Usage:
      python3 bosch_camera.py motion [<cam>]                    # show current
      python3 bosch_camera.py motion [<cam>] --enable           # enable motion
      python3 bosch_camera.py motion [<cam>] --disable          # disable motion
      python3 bosch_camera.py motion [<cam>] --sensitivity S    # set sensitivity
        Sensitivity values: OFF | LOW | MEDIUM_LOW | MEDIUM_HIGH | HIGH | SUPER_HIGH

    API: GET/PUT /v11/video_inputs/{id}/motion
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cams    = resolve_cam(cfg, getattr(args, "cam", None))
    enable  = getattr(args, "enable", False)
    disable = getattr(args, "disable", False)
    sensitivity = getattr(args, "sensitivity", None)

    for name, cam_info in cams.items():
        cam_id = cam_info["id"]
        print(f"\n── Motion Detection: {name} ──────────────────────────────────")

        # GET current settings
        r = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/motion", timeout=10)
        if r.status_code == 401:
            print("  ❌  Token expired.")
            return
        if r.status_code != 200:
            print(f"  ❌  Could not fetch motion settings: HTTP {r.status_code}")
            continue
        data    = r.json()
        current_enabled  = data.get("enabled", False)
        current_sens     = data.get("motionAlarmConfiguration", data.get("sensitivity", "UNKNOWN"))

        enabled_str = "ENABLED" if current_enabled else "DISABLED"
        icon        = "✅" if current_enabled else "❌"
        print(f"  {icon}  Motion: {enabled_str}  Sensitivity: {current_sens}")

        if not enable and not disable and not sensitivity:
            print(f"\n  Run with --enable / --disable / --sensitivity to change.")
            print(f"  E.g.: python3 bosch_camera.py motion {name.lower()} --enable --sensitivity SUPER_HIGH")
            continue

        # Build PUT body
        new_enabled = current_enabled
        new_sens    = current_sens
        if enable:
            new_enabled = True
        if disable:
            new_enabled = False
        if sensitivity:
            new_sens    = sensitivity
            new_enabled = True  # enabling implicitly when setting sensitivity

        body = {"enabled": new_enabled, "motionAlarmConfiguration": new_sens}
        print(f"  🔄  Setting motion → enabled={new_enabled}  sensitivity={new_sens}...")

        pr = session.put(
            f"{CLOUD_API}/v11/video_inputs/{cam_id}/motion",
            json=body,
            headers={"Content-Type": "application/json"},
            timeout=10,
        )
        if pr.status_code in (200, 201, 204):
            state_str = "ENABLED" if new_enabled else "DISABLED"
            icon_new  = "✅" if new_enabled else "❌"
            print(f"  {icon_new}  Motion {state_str}  Sensitivity: {new_sens}")
        else:
            print(f"  ❌  Failed: HTTP {pr.status_code}  {pr.text[:200]}")


def cmd_audio_alarm(cfg: dict, args) -> None:
    """
    Get or set audio alarm detection settings.

    Usage:
      python3 bosch_camera.py audio-alarm [<cam>]               # show current
      python3 bosch_camera.py audio-alarm [<cam>] --enable      # enable
      python3 bosch_camera.py audio-alarm [<cam>] --disable     # disable
      python3 bosch_camera.py audio-alarm [<cam>] --threshold N # set threshold 0-100

    API: GET/PUT /v11/video_inputs/{id}/audioAlarm
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cams    = resolve_cam(cfg, getattr(args, "cam", None))
    enable    = getattr(args, "enable", False)
    disable   = getattr(args, "disable", False)
    threshold = getattr(args, "threshold", None)

    for name, cam_info in cams.items():
        cam_id = cam_info["id"]
        print(f"\n── Audio Alarm: {name} ──────────────────────────────────────")

        r = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/audioAlarm", timeout=10)
        if r.status_code == 401:
            print("  ❌  Token expired.")
            return
        if r.status_code != 200:
            print(f"  ❌  Could not fetch audio alarm settings: HTTP {r.status_code}")
            continue
        data              = r.json()
        current_enabled   = data.get("enabled", False)
        current_threshold = data.get("threshold", 80)

        enabled_str = "ENABLED" if current_enabled else "DISABLED"
        icon        = "🔊" if current_enabled else "🔕"
        print(f"  {icon}  Audio Alarm: {enabled_str}  Threshold: {current_threshold}")

        if not enable and not disable and threshold is None:
            print(f"\n  Run with --enable / --disable / --threshold to change.")
            print(f"  E.g.: python3 bosch_camera.py audio-alarm {name.lower()} --enable --threshold 60")
            continue

        new_enabled   = current_enabled
        new_threshold = current_threshold
        if enable:
            new_enabled = True
        if disable:
            new_enabled = False
        if threshold is not None:
            new_threshold = threshold

        body = {"enabled": new_enabled, "threshold": new_threshold}
        print(f"  🔄  Setting audio alarm → enabled={new_enabled}  threshold={new_threshold}...")

        pr = session.put(
            f"{CLOUD_API}/v11/video_inputs/{cam_id}/audioAlarm",
            json=body,
            headers={"Content-Type": "application/json"},
            timeout=10,
        )
        if pr.status_code in (200, 201, 204):
            state_str = "ENABLED" if new_enabled else "DISABLED"
            icon_new  = "🔊" if new_enabled else "🔕"
            print(f"  {icon_new}  Audio Alarm {state_str}  Threshold: {new_threshold}")
        else:
            print(f"  ❌  Failed: HTTP {pr.status_code}  {pr.text[:200]}")


def cmd_recording(cfg: dict, args) -> None:
    """
    Get or set cloud recording options.

    Usage:
      python3 bosch_camera.py recording [<cam>]                 # show current
      python3 bosch_camera.py recording [<cam>] --sound-on      # include audio
      python3 bosch_camera.py recording [<cam>] --sound-off     # exclude audio

    API: GET/PUT /v11/video_inputs/{id}/recording_options
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cams    = resolve_cam(cfg, getattr(args, "cam", None))
    sound_on  = getattr(args, "sound_on",  False)
    sound_off = getattr(args, "sound_off", False)

    for name, cam_info in cams.items():
        cam_id = cam_info["id"]
        print(f"\n── Recording Options: {name} ──────────────────────────────────")

        r = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/recording_options", timeout=10)
        if r.status_code == 401:
            print("  ❌  Token expired.")
            return
        if r.status_code != 200:
            print(f"  ❌  Could not fetch recording options: HTTP {r.status_code}")
            continue
        data          = r.json()
        current_sound = data.get("recordSound", False)

        sound_str = "ON" if current_sound else "OFF"
        icon      = "🔊" if current_sound else "🔇"
        print(f"  {icon}  Record Sound: {sound_str}")

        if not sound_on and not sound_off:
            print(f"\n  Run with --sound-on or --sound-off to change.")
            print(f"  E.g.: python3 bosch_camera.py recording {name.lower()} --sound-on")
            continue

        new_sound = current_sound
        if sound_on:
            new_sound = True
        if sound_off:
            new_sound = False

        body = {"recordSound": new_sound}
        print(f"  🔄  Setting recordSound → {new_sound}...")

        pr = session.put(
            f"{CLOUD_API}/v11/video_inputs/{cam_id}/recording_options",
            json=body,
            headers={"Content-Type": "application/json"},
            timeout=10,
        )
        if pr.status_code in (200, 201, 204):
            state_str = "ON" if new_sound else "OFF"
            icon_new  = "🔊" if new_sound else "🔇"
            print(f"  {icon_new}  Record Sound: {state_str}")
        else:
            print(f"  ❌  Failed: HTTP {pr.status_code}  {pr.text[:200]}")


# ══════════════════════════ RCP PROTOCOL ══════════════════════════════════════
#
# RCP (Remote Configuration Protocol) is Bosch's proprietary binary protocol
# used internally for low-level camera configuration. It is tunnelled through
# the cloud proxy at:
#   https://proxy-NN.live.cbs.boschsecurity.com:42090/{hash}/rcp.xml
#
# Auth level via cloud proxy hash = 3 (read-only / viewer). Writes require
# a service account (auth level 5) which is not accessible via the cloud proxy.
#
# Session flow:
#   1. WRITE 0xff0c (HELLO) with a fixed payload → response contains sessionid
#   2. WRITE 0xff0d (SESSION_INIT) with the sessionid to activate the session
#   3. READ any command using the sessionid as a query parameter
#
# All payloads are hex-encoded in the URL query string.
# Responses are XML: <rcp_cmd> ... <str>HEX</str> ... </rcp_cmd>

RCP_BASE_PORT = 42090

# Fixed HELLO payload for auth level 3 (viewer) — matches Bosch app behaviour
_RCP_HELLO_PAYLOAD = "0102004000000000040000000000000000010000000000000001000000000000"

# RCP session ID cache: proxy_base → (sessionid, expires_timestamp)
# Avoids re-running the 2-step RCP handshake on every command call.
_RCP_SESSION_CACHE: dict[str, tuple[str, float]] = {}


def rcp_open_connection(cam_id: str, token: str) -> tuple[str, str]:
    """
    Open a REMOTE proxy connection for the given camera.
    Returns (proxy_base_url, proxy_hash_path) where:
      proxy_base_url = 'https://proxy-NN.live.cbs.boschsecurity.com:42090/{hash}'
    Raises RuntimeError on failure.
    """
    headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
    r = requests.put(
        f"{CLOUD_API}/v11/video_inputs/{cam_id}/connection",
        headers=headers,
        json={"type": "REMOTE", "highQualityVideo": False},
        timeout=15,
    )
    if r.status_code != 200:
        raise RuntimeError(f"PUT /connection returned HTTP {r.status_code}")
    data = r.json()
    urls = data.get("urls", [])
    if not urls:
        raise RuntimeError("No URLs in /connection response")
    # urls[0] = "proxy-NN.live.cbs.boschsecurity.com:42090/{hash}"
    raw = urls[0]
    proxy_base = f"https://{raw}"
    return proxy_base, raw


def rcp_session(proxy_base: str) -> str:
    """
    Perform the RCP session handshake via the proxy.
    Step 1: WRITE 0xff0c (HELLO) — get a sessionid back
    Step 2: WRITE 0xff0d (SESSION_INIT) with that sessionid
    Returns sessionid string (e.g. '0x1a2b3c4d').
    Raises RuntimeError on failure.
    """
    import re as _re

    rcp_url = f"{proxy_base}/rcp.xml"

    # Step 1: HELLO (0xff0c WRITE P_OCTET)
    params_hello = {
        "command": "0xff0c",
        "direction": "WRITE",
        "type": "P_OCTET",
        "payload": _RCP_HELLO_PAYLOAD,
    }
    r1 = requests.get(rcp_url, params=params_hello,
                      auth=("", ""), timeout=10)
    if r1.status_code != 200:
        raise RuntimeError(f"RCP HELLO returned HTTP {r1.status_code}")

    m = _re.search(r"<sessionid>(0x[0-9a-fA-F]+)</sessionid>", r1.text)
    if not m:
        # Try to extract from <str> field (hex-encoded XML)
        ms = _re.search(r"<str>([0-9a-fA-F]+)</str>", r1.text)
        if ms:
            raw = bytes.fromhex(ms.group(1))
            m2  = _re.search(rb"(0x[0-9a-fA-F]+)", raw)
            if m2:
                sessionid = m2.group(1).decode()
            else:
                raise RuntimeError(f"Cannot parse sessionid from HELLO response: {r1.text[:400]}")
        else:
            raise RuntimeError(f"No sessionid in HELLO response: {r1.text[:400]}")
    else:
        sessionid = m.group(1)

    # Step 2: SESSION_INIT (0xff0d WRITE P_OCTET sessionid=...)
    params_init = {
        "command": "0xff0d",
        "direction": "WRITE",
        "type": "P_OCTET",
        "sessionid": sessionid,
        "payload": _RCP_HELLO_PAYLOAD,
    }
    r2 = requests.get(rcp_url, params=params_init,
                      auth=("", ""), timeout=10)
    if r2.status_code != 200:
        raise RuntimeError(f"RCP SESSION_INIT returned HTTP {r2.status_code}")

    return sessionid


def rcp_session_cached(proxy_base: str) -> str:
    """Return a cached RCP session ID, calling rcp_session() if missing or expired (5 min TTL).

    Avoids the 2-step handshake overhead (0xff0c + 0xff0d) when multiple RCP
    commands are called in sequence for the same camera within a session.
    """
    now = time.time()
    cached = _RCP_SESSION_CACHE.get(proxy_base)
    if cached:
        session_id, expires_at = cached
        if now < expires_at:
            return session_id
        del _RCP_SESSION_CACHE[proxy_base]
    session_id = rcp_session(proxy_base)
    _RCP_SESSION_CACHE[proxy_base] = (session_id, now + 300.0)
    return session_id


def rcp_read(rcp_url: str, command: str, sessionid: str,
             type_: str = "P_OCTET", num: int = 0) -> bytes | None:
    """
    Send an RCP READ request and return the raw result bytes.
    Returns None if the response is empty (len=0) or an error occurs.

    Args:
        rcp_url:   full URL to rcp.xml, e.g. https://proxy-NN:42090/{hash}/rcp.xml
        command:   hex command code, e.g. '0x0a0f'
        sessionid: session ID from rcp_session()
        type_:     RCP type string, default 'P_OCTET'
        num:       instance number (0 = default)
    """
    import re as _re

    params = {
        "command":   command,
        "direction": "READ",
        "type":      type_,
        "num":       num,
        "sessionid": sessionid,
    }
    try:
        r = requests.get(rcp_url, params=params,
                         auth=("", ""), timeout=10)
    except Exception as e:
        return None

    if r.status_code != 200:
        return None

    # Parse XML — result is in <str>HEX</str>
    m = _re.search(r"<str>([0-9a-fA-F]*)</str>", r.text)
    if not m:
        return None
    hex_str = m.group(1)
    if not hex_str:
        return None   # empty result
    try:
        return bytes.fromhex(hex_str)
    except ValueError:
        return None


def rcp_parse_utf16be_strings(data: bytes) -> list[str]:
    """
    Parse a UTF-16-BE encoded string list (as used in RCP 0x0c38 alarm catalog).
    Splits on null words (\\x00\\x00) and decodes each non-empty segment.
    Returns list of strings.
    """
    results = []
    # Split on null word boundaries
    i = 0
    current = bytearray()
    while i < len(data) - 1:
        word = data[i:i+2]
        if word == b"\x00\x00":
            if current:
                try:
                    s = current.decode("utf-16-be").strip("\x00").strip()
                    if s:
                        results.append(s)
                except Exception:
                    pass
                current = bytearray()
        else:
            current += word
        i += 2
    if current:
        try:
            s = current.decode("utf-16-be").strip("\x00").strip()
            if s:
                results.append(s)
        except Exception:
            pass
    return results


def rcp_parse_clock(data: bytes) -> str:
    """
    Parse the 8-byte RCP clock from command 0x0a0f.
    Format: YYYY(2B big-endian) MM(1B) DD(1B) HH(1B) MM(1B) SS(1B) DOW(1B)
    Returns a formatted datetime string, e.g. '2026-03-22 05:54:25'.
    """
    if len(data) < 7:
        return f"(invalid clock data: {data.hex()})"
    try:
        year  = (data[0] << 8) | data[1]
        month = data[2]
        day   = data[3]
        hour  = data[4]
        minute = data[5]
        second = data[6]
        return f"{year:04d}-{month:02d}-{day:02d} {hour:02d}:{minute:02d}:{second:02d}"
    except Exception as e:
        return f"(parse error: {e})"


def rcp_parse_string(data: bytes) -> str:
    """Decode a null-terminated ASCII/UTF-8 string from RCP data bytes."""
    try:
        return data.rstrip(b"\x00").decode("utf-8", errors="replace")
    except Exception:
        return data.hex()


def rcp_parse_ip(data: bytes) -> str:
    """Parse a 4-byte big-endian IPv4 address from RCP data."""
    if len(data) >= 4:
        return f"{data[0]}.{data[1]}.{data[2]}.{data[3]}"
    return data.hex()


def rcp_parse_word(data: bytes) -> int | None:
    """Parse a 2-byte big-endian unsigned integer (T_WORD) from RCP data."""
    if len(data) >= 2:
        return (data[0] << 8) | data[1]
    return None


def _rcp_setup(cam_info: dict, token: str) -> tuple[str, str]:
    """
    Open a REMOTE connection and perform RCP session handshake.
    Returns (rcp_url, sessionid).
    Prints status messages. Raises RuntimeError on failure.
    """
    cam_id = cam_info["id"]
    print(f"  🌐  Opening REMOTE proxy connection...")
    proxy_base, _ = rcp_open_connection(cam_id, token)
    print(f"  🔗  Proxy: {proxy_base}")
    print(f"  🤝  RCP session handshake (cached)...")
    sessionid = rcp_session_cached(proxy_base)
    print(f"  ✅  Session: {sessionid}")
    rcp_url = f"{proxy_base}/rcp.xml"
    return rcp_url, sessionid


def cmd_rcp(cfg: dict, args) -> None:
    """
    RCP — Remote Configuration Protocol reads via cloud proxy.

    Subcommands:
      info      — camera identity: MAC, product name, FQDN, LAN IP
      clock     — real-time camera clock (0x0a0f)
      snapshot  — RCP JPEG thumbnail 320×180 (0x099e, resolution from 0x0a88) — save + open
      alarms    — alarm catalog from 0x0c38 (UTF-16-BE)
      privacy   — privacy mask state read (0x0d00)
      dimmer    — LED dimmer value 0-100 (0x0c22 T_WORD)
      motion    — motion zone count from 0x0c0a
      services  — network services list from 0x0c62
      frame     — raw video frame 320x180 YUV422 (0x0c98) → JPEG
      script    — IVA automation script gzip (0x09f3) → text
      iva       — IVA rule types + resiMotion config (0x0ba9 + 0x0a1b)
      bitrate   — bitrate ladder tiers in kbps (0x0c81)
      all       — run all of the above

    The cloud proxy hash acts as the credential — no username/password needed.
    Auth level via cloud proxy = 3 (read-only). Writes require auth level 5.
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cam_arg = getattr(args, "cam", None)
    sub     = (getattr(args, "sub", None) or "").lower()

    # Allow "rcp info" without a camera name (sub parsed as cam_arg)
    RCP_SUBS = ("info", "clock", "snapshot", "alarms", "privacy",
                "dimmer", "motion", "services", "frame", "script", "iva", "bitrate", "all")
    if cam_arg and cam_arg.lower() in RCP_SUBS and not sub:
        sub, cam_arg = cam_arg.lower(), None

    if not sub:
        print("\n  ℹ️   Usage: python3 bosch_camera.py rcp [camera] <subcommand>")
        print("  Subcommands: info | clock | snapshot | alarms | privacy | dimmer | motion | services | frame | script | iva | bitrate | all")
        return

    cams = resolve_cam(cfg, cam_arg)

    for name, cam_info in cams.items():
        print(f"\n── RCP: {name} ({sub}) ─────────────────────────────────────────")

        try:
            rcp_url, sessionid = _rcp_setup(cam_info, token)
        except RuntimeError as e:
            print(f"  ❌  RCP setup failed: {e}")
            continue

        run_all = (sub == "all")

        # ── info ──────────────────────────────────────────────────────────────
        if sub in ("info", "all"):
            print(f"\n  ── Identity ──────────────────────────────────────────────")
            # 0x0aea — product name (null-terminated ASCII)
            d = rcp_read(rcp_url, "0x0aea", sessionid)
            if d:
                print(f"  Product:    {rcp_parse_string(d)}")
            else:
                print(f"  Product:    (not available)")
            # 0x0aee — cloud FQDN
            d = rcp_read(rcp_url, "0x0aee", sessionid)
            if d:
                print(f"  Cloud FQDN: {rcp_parse_string(d)}")
            else:
                print(f"  Cloud FQDN: (not available)")
            # 0x0a36 — LAN IP (4-byte or string)
            d = rcp_read(rcp_url, "0x0a36", sessionid)
            if d:
                ip_str = rcp_parse_ip(d) if len(d) == 4 else rcp_parse_string(d)
                print(f"  LAN IP:     {ip_str}  (via RCP)")
            else:
                print(f"  LAN IP:     (not available)")
            # 0x0a30 — MAC address (6 bytes)
            d = rcp_read(rcp_url, "0x0a30", sessionid)
            if d and len(d) >= 6:
                mac_str = ":".join(f"{b:02x}" for b in d[:6])
                print(f"  MAC:        {mac_str}  (via RCP)")
            elif d:
                print(f"  MAC:        {rcp_parse_string(d)}")
            else:
                print(f"  MAC:        (not available)")

        # ── clock ─────────────────────────────────────────────────────────────
        if sub in ("clock", "all"):
            print(f"\n  ── Camera Clock ──────────────────────────────────────────")
            d = rcp_read(rcp_url, "0x0a0f", sessionid)
            if d:
                print(f"  Clock:      {rcp_parse_clock(d)}  (camera local time)")
                print(f"  Raw:        {d.hex()}")
            else:
                print(f"  Clock:      (not available)")

        # ── snapshot ──────────────────────────────────────────────────────────
        if sub in ("snapshot", "all"):
            print(f"\n  ── RCP Thumbnail Snapshot ────────────────────────────────")
            # Confirm resolution via 0x0a88 (returns 8B: width 4B BE + height 4B BE)
            import struct as _struct
            res_d = rcp_read(rcp_url, "0x0a88", sessionid)
            if res_d and len(res_d) >= 8:
                w, h = _struct.unpack(">II", res_d[:8])
                print(f"  Resolution: {w}×{h}  (from 0x0a88)")
            else:
                w, h = 320, 180
                print(f"  Resolution: {w}×{h}  (assumed — 0x0a88 not available)")
            d = rcp_read(rcp_url, "0x099e", sessionid)
            if d and d[:2] == b"\xff\xd8":  # JPEG magic
                suffix = f"_rcp_thumb_{name.replace(' ', '_')}.jpg"
                tmp = os.path.join(BASE_DIR, f"rcp_snapshot{suffix}")
                with open(tmp, "wb") as f:
                    f.write(d)
                print(f"  Thumbnail:  {w}×{h} JPEG  ({len(d):,} bytes)")
                print(f"  Saved:      {tmp}")
                open_file(tmp)
            elif d:
                # Not JPEG — save raw for inspection
                tmp = os.path.join(BASE_DIR, f"rcp_snapshot_{name.replace(' ', '_')}.bin")
                with open(tmp, "wb") as f:
                    f.write(d)
                print(f"  Data:       {len(d)} bytes (not JPEG — saved as .bin: {tmp})")
                print(f"  Header:     {d[:16].hex()}")
            else:
                print(f"  Snapshot:   (not available)")

        # ── alarms ────────────────────────────────────────────────────────────
        if sub in ("alarms", "all"):
            print(f"\n  ── Alarm Catalog (0x0c38) ────────────────────────────────")
            d = rcp_read(rcp_url, "0x0c38", sessionid)
            if d:
                strings = rcp_parse_utf16be_strings(d)
                if strings:
                    for i, s in enumerate(strings):
                        print(f"  [{i:02d}] {s}")
                else:
                    print(f"  (no strings decoded — raw {len(d)} bytes: {d[:32].hex()}...)")
            else:
                print(f"  Alarms:     (not available)")

        # ── privacy ───────────────────────────────────────────────────────────
        if sub in ("privacy", "all"):
            print(f"\n  ── Privacy Mask State (0x0d00) ───────────────────────────")
            d = rcp_read(rcp_url, "0x0d00", sessionid)
            if d and len(d) >= 1:
                state_byte = d[1] if len(d) > 1 else d[0]
                state_str  = "ON (masked)" if state_byte else "OFF (visible)"
                icon       = "🔒" if state_byte else "👁️"
                print(f"  {icon}  Privacy mask: {state_str}  (byte[1]={state_byte:#04x})")
                print(f"  Raw:          {d.hex()}")
            else:
                print(f"  Privacy:    (not available)")

        # ── dimmer ────────────────────────────────────────────────────────────
        if sub in ("dimmer", "all"):
            print(f"\n  ── LED Dimmer (0x0c22) ───────────────────────────────────")
            d = rcp_read(rcp_url, "0x0c22", sessionid, type_="T_WORD")
            if d is None:
                # Try P_OCTET fallback
                d = rcp_read(rcp_url, "0x0c22", sessionid)
            if d:
                val = rcp_parse_word(d)
                if val is not None:
                    print(f"  Dimmer:     {val}  (0=off, 100=max)")
                else:
                    print(f"  Dimmer raw: {d.hex()}")
            else:
                print(f"  Dimmer:     (not available)")

        # ── motion ────────────────────────────────────────────────────────────
        if sub in ("motion", "all"):
            print(f"\n  ── Motion Zones (0x0c0a) ─────────────────────────────────")
            d = rcp_read(rcp_url, "0x0c0a", sessionid)
            if d:
                # Each zone is typically 8 bytes: x1(2B) y1(2B) x2(2B) y2(2B) in 0-10000 units
                zone_size = 8
                n_zones   = len(d) // zone_size
                print(f"  Zones:      {n_zones} zone(s)  ({len(d)} bytes raw)")
                for z in range(n_zones):
                    chunk = d[z*zone_size:(z+1)*zone_size]
                    if len(chunk) == 8:
                        x1 = (chunk[0] << 8) | chunk[1]
                        y1 = (chunk[2] << 8) | chunk[3]
                        x2 = (chunk[4] << 8) | chunk[5]
                        y2 = (chunk[6] << 8) | chunk[7]
                        print(f"  Zone {z}:     ({x1},{y1}) → ({x2},{y2})  [0-10000 coords]")
                    else:
                        print(f"  Zone {z}:     {chunk.hex()}")
            else:
                print(f"  Motion:     (not available)")

        # ── services ──────────────────────────────────────────────────────────
        if sub in ("services", "all"):
            print(f"\n  ── Network Services (0x0c62) ─────────────────────────────")
            d = rcp_read(rcp_url, "0x0c62", sessionid)
            if d:
                # Services list is typically null-terminated ASCII strings
                services = [s for s in d.decode("ascii", errors="replace").split("\x00") if s.strip()]
                if services:
                    for svc in services:
                        print(f"  Service:    {svc}")
                else:
                    print(f"  Services raw: {len(d)} bytes  {d[:48].hex()}")
            else:
                print(f"  Services:   (not available)")

        # ── frame ─────────────────────────────────────────────────────────────
        if sub in ("frame", "all"):
            print(f"\n  ── Raw Frame (0x0c98) ────────────────────────────────────")
            d = rcp_read(rcp_url, "0x0c98", sessionid)
            if d and len(d) == 115200:
                safe_name = name.replace(' ', '_')
                try:
                    import numpy as np
                    from PIL import Image
                    # YUV422 interleaved (YUYV): each 4 bytes = 2 pixels: Y0 U Y1 V
                    raw = np.frombuffer(d, dtype=np.uint8).reshape(180, 320, 2)
                    # Expand to YUV444
                    y = raw[:, :, 0].astype(np.float32)
                    uv = raw[:, :, 1].astype(np.float32)
                    u = np.repeat(uv[:, 0::2][:, :, np.newaxis], 2, axis=1).reshape(180, 320) - 128
                    v = np.repeat(uv[:, 1::2][:, :, np.newaxis], 2, axis=1).reshape(180, 320) - 128
                    r = np.clip(y + 1.402 * v, 0, 255).astype(np.uint8)
                    g = np.clip(y - 0.344136 * u - 0.714136 * v, 0, 255).astype(np.uint8)
                    b = np.clip(y + 1.772 * u, 0, 255).astype(np.uint8)
                    rgb = np.stack([r, g, b], axis=2)
                    img = Image.fromarray(rgb)
                    path = os.path.join(BASE_DIR, f"rcp_frame_{safe_name}.jpg")
                    img.save(path, "JPEG")
                    print(f"  Frame:      320x180 YUV422 ({len(d):,} bytes) -> saved as JPEG: {path}")
                    open_file(path)
                except Exception:
                    path = os.path.join(BASE_DIR, f"rcp_frame_{safe_name}.yuv")
                    with open(path, "wb") as f:
                        f.write(d)
                    print(f"  Frame:      320x180 YUV422 ({len(d):,} bytes) -> saved as raw YUV: {path}")
                    print(f"  Note:       Install numpy + Pillow for JPEG conversion")
            elif d:
                safe_name = name.replace(' ', '_')
                path = os.path.join(BASE_DIR, f"rcp_frame_{safe_name}.bin")
                with open(path, "wb") as f:
                    f.write(d)
                print(f"  Frame:      {len(d):,} bytes (unexpected size — saved as .bin: {path})")
            else:
                print(f"  Frame:      (not available)")

        # ── script ────────────────────────────────────────────────────────────
        if sub in ("script", "all"):
            print(f"\n  ── IVA Automation Script (0x09f3) ────────────────────────")
            d = rcp_read(rcp_url, "0x09f3", sessionid)
            if d and d[:2] == b'\x1f\x8b':  # gzip magic
                import gzip
                try:
                    text = gzip.decompress(d).decode('utf-8', errors='replace')
                    print(f"  Script:     {len(d):,} bytes compressed -> {len(text):,} chars decompressed")
                    for line in text.splitlines():
                        print(f"  {line}")
                except Exception as exc:
                    print(f"  Decompress error: {exc}")
                    print(f"  Raw header: {d[:16].hex()}")
            elif d:
                print(f"  Data:       {len(d):,} bytes (not gzip)")
                print(f"  Raw header: {d[:16].hex()}")
            else:
                print(f"  Script:     (not available)")

        # ── iva ───────────────────────────────────────────────────────────────
        if sub in ("iva", "all"):
            print(f"\n  ── IVA Rules & resiMotion Config ─────────────────────────")
            # 0x0ba9 — IVA rule type names (null-terminated ASCII list)
            d = rcp_read(rcp_url, "0x0ba9", sessionid)
            if d:
                rule_names = [s for s in d.decode("ascii", errors="replace").split("\x00") if s.strip()]
                if rule_names:
                    print(f"  IVA rule types ({len(rule_names)}):")
                    for rn in rule_names:
                        print(f"    • {rn}")
                else:
                    print(f"  IVA rule types: raw {len(d)} bytes  {d[:32].hex()}")
            else:
                print(f"  IVA rule types: (not available)")
            # 0x0a1b — resiMotion config (motion detection polygon + sensitivity params)
            d = rcp_read(rcp_url, "0x0a1b", sessionid)
            if d:
                try:
                    text = d.decode("utf-8", errors="replace").rstrip("\x00")
                    print(f"  resiMotion config ({len(d):,} bytes):")
                    for line in text.splitlines():
                        print(f"    {line}")
                except Exception:
                    print(f"  resiMotion raw: {len(d):,} bytes  {d[:32].hex()}")
            else:
                print(f"  resiMotion config: (not available)")

        # ── bitrate ───────────────────────────────────────────────────────────────
        if sub in ("bitrate", "all"):
            print(f"\n  ── Bitrate Ladder (0x0c81) ───────────────────────────────")
            d = rcp_read(rcp_url, "0x0c81", sessionid)
            if d and len(d) >= 4:
                import struct as _s
                # Ladder is a series of big-endian uint32 values (kbps)
                n = len(d) // 4
                tiers = [_s.unpack(">I", d[i*4:(i+1)*4])[0] for i in range(n)]
                labels = ["low", "medium-low", "medium", "medium-high", "high"]
                for i, kbps in enumerate(tiers):
                    label = labels[i] if i < len(labels) else f"tier{i}"
                    marker = " ←" if i == len(tiers)-1 else ""
                    print(f"  [{label}]  {kbps:,} kbps  ({kbps//1000:.1f} Mbps){marker}")
                print(f"\n  Note: highQualityVideo=true selects the highest tier")
            else:
                print(f"  Bitrate: (not available)")

        print()


def cmd_token(cfg: dict, args) -> None:
    """Show token status and optionally renew it.

    Usage:
      python3 bosch_camera.py token          → show current status
      python3 bosch_camera.py token fix      → renew via refresh_token (or browser)
      python3 bosch_camera.py token browser  → force new browser login
    """
    import base64 as _b64

    action = getattr(args, "cam", None) or getattr(args, "action", None)
    if action:
        action = action.lower()

    acct    = cfg.get("account", {})
    token   = acct.get("bearer_token", "").strip()
    refresh = acct.get("refresh_token", "").strip()

    print("\n── Token Status ─────────────────────────────────────────────")
    if token:
        print(f"  Access token:  {token[:24]}...  ({len(token)} chars)")
        try:
            parts = token.split(".")
            pad   = len(parts[1]) % 4
            info  = json.loads(_b64.urlsafe_b64decode(parts[1] + "=" * pad))
            exp   = info.get("exp", 0)
            exp_dt = datetime.datetime.fromtimestamp(exp)
            diff   = exp_dt - datetime.datetime.now()
            mins   = int(diff.total_seconds() / 60)
            if mins > 0:
                status = f"valid ~{mins}m ✅"
            else:
                status = f"EXPIRED {abs(mins)}m ago ❌"
            print(f"  Email:         {info.get('email', info.get('preferred_username', ''))}")
            print(f"  Expires:       {exp_dt.strftime('%Y-%m-%d %H:%M')}  ({status})")
            expired = mins <= 0
        except Exception:
            print(f"  Status:        {check_token_age(cfg)}")
            expired = False
    else:
        print("  Access token:  (none)")
        expired = True

    if refresh:
        print(f"  Refresh token: {refresh[:20]}...  ({len(refresh)} chars) — auto-renewal ✅")
    else:
        print("  Refresh token: (none) — browser login needed")

    if action in ("fix", "refresh", "renew", "browser"):
        print()
        force_browser = (action == "browser")
        try:
            from get_token import get_token_auto
            new_token = get_token_auto(cfg, force_browser=force_browser)
            if new_token:
                print(f"\n  ✅  Token renewed successfully.")
            else:
                print(f"\n  ❌  Token renewal failed.")
        except ImportError:
            print("  ❌  get_token.py not found in the same folder.")
    elif expired:
        print()
        print("  ➡️   To fix: python3 bosch_camera.py token fix")
    print()


def cmd_rescan(cfg: dict, args) -> None:
    """Re-discover cameras from API and update config."""
    token   = get_token(cfg)
    session = make_session(token)
    print("\n  🔍  Re-scanning cameras...")
    cameras = discover_cameras(cfg, session)
    print(f"\n  Found {len(cameras)} camera(s):")
    for name, cam in cameras.items():
        print(f"    • {name}  ({cam['model']})  ID: {cam['id']}")


# ══════════════════════════ INTERACTIVE MENU ══════════════════════════════════

def cmd_menu(cfg: dict) -> None:
    """Interactive numbered menu."""
    cameras = cfg.get("cameras", {})
    cam_names = list(cameras.keys())

    # Auto-renew token silently if expired before displaying status
    token = cfg["account"].get("bearer_token", "").strip()
    if not token or _is_token_expired(token):
        get_token(cfg)

    print("""
╔══════════════════════════════════════════════════════════╗
║        Bosch Smart Home Camera — Control Panel           ║
╚══════════════════════════════════════════════════════════╝
""")
    print(f"  Version: {VERSION}")
    print(f"  Config: {CONFIG_FILE}")
    print(f"  Token:  {check_token_age(cfg)}")
    if cam_names:
        print(f"  Cameras in config: {', '.join(cam_names)}")
    else:
        print("  ⚠️   No cameras in config — choose option 12 to scan")
    print()

    print("  1)  Camera status (ONLINE / OFFLINE)")
    print("  2)  Camera info (full details + stream URLs)")
    for i, name in enumerate(cam_names, start=3):
        print(f"  {i})  Latest event snapshot — {name}")
    offset = 3 + len(cam_names)

    print(f"  {offset})  Latest event snapshot — ALL cameras")
    offset += 1

    liveshot_start = offset
    for i, name in enumerate(cam_names, start=offset):
        print(f"  {i})  Live snapshot — {name}  (remote/local)")
        offset += 1

    live_start = offset
    for i, name in enumerate(cam_names, start=offset):
        print(f"  {i})  Live stream — {name} (ffplay, audio+video)")
        offset += 1

    live_vlc_start = offset
    for i, name in enumerate(cam_names, start=offset):
        print(f"  {i})  Live stream — {name} (VLC, audio+video)")
        offset += 1

    live_local_start = offset
    for i, name in enumerate(cam_names, start=offset):
        print(f"  {i})  Live stream LOCAL — {name} (LAN, TLS proxy)")
        offset += 1

    # ── Camera controls ───────────────────────────────────────────────────────
    print()
    print("  ── Privacy ──────────────────────────────────────────────────")
    privacy_start = offset
    for name in cam_names:
        print(f"  {offset})  Privacy ON  — {name}")
        offset += 1
        print(f"  {offset})  Privacy OFF — {name}")
        offset += 1

    # Light — only cameras with has_light=True
    light_cams = [n for n in cam_names if cameras.get(n, {}).get("has_light", False)]
    light_start = offset
    if light_cams:
        print()
        print("  ── Camera Light ─────────────────────────────────────────────")
        for name in light_cams:
            print(f"  {offset})  Light ON  — {name}")
            offset += 1
            print(f"  {offset})  Light OFF — {name}")
            offset += 1

    print()
    print("  ── Notifications ────────────────────────────────────────────")
    notif_start = offset
    for name in cam_names:
        print(f"  {offset})  Notifications ON  — {name}")
        offset += 1
        print(f"  {offset})  Notifications OFF — {name}")
        offset += 1

    # Pan — only cameras with pan_limit > 0
    pan_cams = [n for n in cam_names if cameras.get(n, {}).get("pan_limit", 0) > 0]
    pan_start = offset
    pan_actions = [("left", "◀◀ Full left"), ("center", "■  Center (0°)"), ("right", "▶▶ Full right")]
    if pan_cams:
        print()
        print("  ── Pan ──────────────────────────────────────────────────────")
        for name in pan_cams:
            for action_key, label in pan_actions:
                lim = cameras[name].get("pan_limit", 120)
                lim_str = f"-{lim}°" if action_key == "left" else (f"+{lim}°" if action_key == "right" else "0°")
                print(f"  {offset})  Pan {label} ({lim_str}) — {name}")
                offset += 1

    print()
    print("  ── Intercom ─────────────────────────────────────────────────")
    intercom_start = offset
    for name in cam_names:
        print(f"  {offset})  Intercom (listen) — {name}")
        offset += 1

    print()
    print("  ── Siren ────────────────────────────────────────────────────")
    siren_start = offset
    for name in cam_names:
        print(f"  {offset})  Siren (acoustic alarm) — {name}")
        offset += 1

    print()
    print("  ── Unread Events ────────────────────────────────────────────")
    unread_item = offset
    print(f"  {offset})  Show unread event counts")
    offset += 1

    print()
    print("  ── Token ────────────────────────────────────────────────────")
    token_item = offset
    print(f"  {offset})  Show token status / renew")
    offset += 1

    print()
    print(f"  {offset})  Show config file")
    config_item = offset
    offset += 1
    print(f"  {offset})  Re-scan cameras")
    rescan_item = offset
    offset += 1
    print("  q)  Exit")
    print()

    choice = input("  Enter choice: ").strip()

    class A:
        cam     = None
        action  = None
        sub     = None
        limit   = None
        re_download = False
        live    = False
        vlc     = False
        local   = False
        full    = False
        minutes = None

    a = A()

    if choice.lower() in ("q", "quit", "exit", "0"):
        sys.exit(0)

    try:
        c = int(choice)
    except ValueError:
        return  # empty Enter or invalid → just redraw menu

    if c == 1:          cmd_status(cfg, a)
    elif c == 2:        cmd_info(cfg, a)
    elif 3 <= c < 3 + len(cam_names):
        a.cam = cam_names[c - 3]
        a.live = False
        cmd_snapshot(cfg, a)
    elif c == 3 + len(cam_names):
        a.live = False
        cmd_snapshot(cfg, a)
    elif liveshot_start <= c < liveshot_start + len(cam_names):
        a.cam  = cam_names[c - liveshot_start]
        a.live = True
        cmd_snapshot(cfg, a)
    elif live_start <= c < live_start + len(cam_names):
        a.cam = cam_names[c - live_start]
        a.vlc = False
        cmd_live(cfg, a)
    elif live_vlc_start <= c < live_vlc_start + len(cam_names):
        a.cam = cam_names[c - live_vlc_start]
        a.vlc = True
        cmd_live(cfg, a)
    elif live_local_start <= c < live_local_start + len(cam_names):
        a.cam = cam_names[c - live_local_start]
        a.local = True
        a.quality = "high"  # LOCAL always best quality
        cmd_live(cfg, a)
    # Privacy
    elif privacy_start <= c < privacy_start + len(cam_names) * 2:
        idx = c - privacy_start
        a.cam    = cam_names[idx // 2]
        a.action = "on" if idx % 2 == 0 else "off"
        cmd_privacy(cfg, a)
    # Light (only light_cams)
    elif light_cams and light_start <= c < light_start + len(light_cams) * 2:
        idx = c - light_start
        a.cam    = light_cams[idx // 2]
        a.action = "on" if idx % 2 == 0 else "off"
        cmd_light(cfg, a)
    # Notifications
    elif notif_start <= c < notif_start + len(cam_names) * 2:
        idx = c - notif_start
        a.cam    = cam_names[idx // 2]
        a.action = "on" if idx % 2 == 0 else "off"
        cmd_notifications(cfg, a)
    # Pan (only pan_cams)
    elif pan_cams and pan_start <= c < pan_start + len(pan_cams) * len(pan_actions):
        idx = c - pan_start
        a.cam    = pan_cams[idx // len(pan_actions)]
        a.action = pan_actions[idx % len(pan_actions)][0]
        cmd_pan(cfg, a)
    # Intercom
    elif intercom_start <= c < intercom_start + len(cam_names):
        a.cam = cam_names[c - intercom_start]
        a.duration = 60
        a.speaker_level = 50
        cmd_intercom(cfg, a)
    # Siren
    elif siren_start <= c < siren_start + len(cam_names):
        a.cam = cam_names[c - siren_start]
        cmd_siren(cfg, a)
    # Unread
    elif c == unread_item:
        cmd_unread(cfg, a)
    elif c == token_item:
        a.action = "fix"
        cmd_token(cfg, a)
    elif c == config_item:
        cmd_config(cfg, a)
    elif c == rescan_item:
        cmd_rescan(cfg, a)
    else:
        print(f"  Unknown choice: {c}")

    input("\n  Press Enter to return to menu...")


def cmd_autofollow(cfg: dict, args) -> None:
    """Get or set auto-follow for a 360 camera via the Bosch cloud API.

    Usage:
      python3 bosch_camera.py autofollow [cam-name]        → show current state
      python3 bosch_camera.py autofollow [cam-name] on     → enable auto-follow
      python3 bosch_camera.py autofollow [cam-name] off    → disable auto-follow

    API: GET/PUT /v11/video_inputs/{id}/autofollow
         Body: {"result": true/false}
         Response: HTTP 204 on success.
    Only available for cameras with featureSupport.panLimit > 0 (CAMERA_360).
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cam_arg = getattr(args, "cam", None)
    action  = getattr(args, "action", None)

    if cam_arg and cam_arg.lower() in ("on", "off") and action is None:
        action  = cam_arg.lower()
        cam_arg = None

    cams = resolve_cam(cfg, cam_arg)

    for name, cam_info in cams.items():
        cam_id    = cam_info["id"]
        pan_limit = cam_info.get("pan_limit", 0)

        print(f"\n── Auto-Follow: {name} ─────────────────────────────────────")
        if not pan_limit:
            print(f"  ℹ️   This camera does not support auto-follow (panLimit=0).")
            continue

        r = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/autofollow", timeout=10)
        if r.status_code != 200:
            print(f"  ❌  Could not fetch auto-follow state: HTTP {r.status_code}")
            continue
        current = r.json().get("result", False)
        icon = "🎯" if current else "⏸️"
        print(f"  {icon}  Auto-follow:  {'ENABLED' if current else 'DISABLED'}")

        if action is None:
            print(f"\n  Run with 'on' or 'off' to toggle. E.g.:")
            print(f"    python3 bosch_camera.py autofollow {name.lower()} on")
            continue

        new_state = action == "on"
        if new_state == current:
            print(f"  ✅  Already {'ENABLED' if current else 'DISABLED'} — no change needed.")
            continue

        print(f"  🔄  Setting auto-follow → {'ENABLED' if new_state else 'DISABLED'}...")
        pr = session.put(
            f"{CLOUD_API}/v11/video_inputs/{cam_id}/autofollow",
            json={"result": new_state},
            headers={"Content-Type": "application/json"},
            timeout=10,
        )
        if pr.status_code in (200, 201, 204):
            icon_new = "🎯" if new_state else "⏸️"
            print(f"  {icon_new}  Auto-follow {'ENABLED' if new_state else 'DISABLED'}.")
        else:
            print(f"  ❌  Failed: HTTP {pr.status_code}  {pr.text[:200]}")


def cmd_siren(cfg: dict, args) -> None:
    """Trigger the acoustic alarm (siren) on a camera.

    Usage:
      python3 bosch_camera.py siren <cam-name>

    API: PUT /v11/video_inputs/{id}/acoustic_alarm
    Note: Only supported on CAMERA_360 (indoor). Outdoor cameras return HTTP 442.
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cams    = resolve_cam(cfg, getattr(args, "cam", None))

    if len(cams) != 1:
        print("  ❌  Siren requires exactly one camera. Specify the camera name.")
        return

    cam_name, cam_info = next(iter(cams.items()))
    cam_id = cam_info["id"]

    print(f"\n── Siren: {cam_name} ──────────────────────────────────────")
    print(f"  🔔  Triggering acoustic alarm...")

    r = session.put(
        f"{CLOUD_API}/v11/video_inputs/{cam_id}/acoustic_alarm",
        json={"enabled": True},
        timeout=10,
    )
    if r.status_code in (200, 201, 204):
        print(f"  ✅  Siren activated!")
    elif r.status_code == 442:
        print(f"  ⚠️  Siren not supported on this camera model (HTTP 442)")
    else:
        print(f"  ❌  Failed: HTTP {r.status_code}  {r.text[:200]}")


def cmd_unread(cfg: dict, args) -> None:
    """Show unread event count per camera.

    Usage:
      python3 bosch_camera.py unread

    API: GET /v11/video_inputs/{id}/unread_events_count
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cams    = resolve_cam(cfg, getattr(args, "cam", None))

    print(f"\n── Unread Events ──────────────────────────────────────")
    for name, cam_info in cams.items():
        cam_id = cam_info["id"]
        r = session.get(
            f"{CLOUD_API}/v11/video_inputs/{cam_id}/unread_events_count",
            timeout=10,
        )
        if r.status_code == 200:
            data = r.json()
            count = data.get("count", data) if isinstance(data, dict) else data
            print(f"  📬  {name}: {count} unread events")
        elif r.status_code == 442:
            print(f"  ⚠️  {name}: endpoint not supported (HTTP 442)")
        else:
            print(f"  ❌  {name}: HTTP {r.status_code}")


def cmd_privacy_sound(cfg: dict, args) -> None:
    """Get or set privacy sound override for a camera.

    Usage:
      python3 bosch_camera.py privacy-sound [cam-name]        → show current state
      python3 bosch_camera.py privacy-sound [cam-name] on     → enable privacy sound
      python3 bosch_camera.py privacy-sound [cam-name] off    → disable privacy sound

    API: GET/PUT /v11/video_inputs/{id}/privacy_sound_override
         Body: {"result": true/false}
         Response: {"result": true/false}
    When enabled, the camera plays an audible indicator when privacy mode changes.
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cam_arg = getattr(args, "cam", None)
    action  = getattr(args, "action", None)

    if cam_arg and cam_arg.lower() in ("on", "off") and action is None:
        action  = cam_arg.lower()
        cam_arg = None

    cams = resolve_cam(cfg, cam_arg)

    for name, cam_info in cams.items():
        cam_id = cam_info["id"]
        print(f"\n── Privacy Sound: {name} ─────────────────────────────────────")

        r = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/privacy_sound_override", timeout=10)
        if r.status_code == 401:
            print("  ❌  Token expired.")
            return
        if r.status_code == 442:
            print(f"  ⚠️   Privacy sound not supported on this camera model (HTTP 442)")
            continue
        if r.status_code == 444:
            print(f"  ⚠️   Camera offline or unavailable for this operation")
            try:
                print(f"       {r.json()}")
            except Exception:
                print(f"       {r.text[:200]}")
            continue
        if r.status_code != 200:
            print(f"  ❌  Could not fetch privacy sound state: HTTP {r.status_code}")
            continue
        data    = r.json()
        current = data.get("result", False)
        icon    = "🔊" if current else "🔇"
        print(f"  {icon}  Privacy sound:  {'ENABLED' if current else 'DISABLED'}")

        if action is None:
            print(f"\n  Run with 'on' or 'off' to toggle. E.g.:")
            print(f"    python3 bosch_camera.py privacy-sound {name.lower()} on")
            continue

        new_state = action == "on"
        if new_state == current:
            print(f"  ✅  Already {'ENABLED' if current else 'DISABLED'} — no change needed.")
            continue

        print(f"  🔄  Setting privacy sound → {'ENABLED' if new_state else 'DISABLED'}...")
        pr = session.put(
            f"{CLOUD_API}/v11/video_inputs/{cam_id}/privacy_sound_override",
            json={"result": new_state},
            headers={"Content-Type": "application/json"},
            timeout=10,
        )
        if pr.status_code in (200, 201, 204):
            icon_new = "🔊" if new_state else "🔇"
            print(f"  {icon_new}  Privacy sound {'ENABLED' if new_state else 'DISABLED'}.")
        elif pr.status_code == 444:
            print(f"  ⚠️   Camera offline or unavailable for this operation")
            try:
                print(f"       {pr.json()}")
            except Exception:
                print(f"       {pr.text[:200]}")
        else:
            print(f"  ❌  Failed: HTTP {pr.status_code}  {pr.text[:200]}")


def cmd_rules(cfg: dict, args) -> None:
    """Manage camera automation rules (time-based schedules).

    Usage:
      python3 bosch_camera.py rules [cam]                                            → list all rules
      python3 bosch_camera.py rules [cam] add --name NAME --start HH:MM --end HH:MM --days 0,1,2,3,4,5,6
      python3 bosch_camera.py rules [cam] edit --id RULE_ID [--active|--inactive] [--name NAME] [--start HH:MM] [--end HH:MM] [--days 0,1,2,3,4,5,6]
      python3 bosch_camera.py rules [cam] delete --id RULE_ID

    API: GET/POST/PUT/DELETE /v11/video_inputs/{id}/rules
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cam_arg = getattr(args, "cam", None)
    sub     = getattr(args, "sub", None)

    # Allow "rules add" without camera name
    RULES_SUBS = ("add", "edit", "delete")
    if cam_arg and cam_arg.lower() in RULES_SUBS and not sub:
        sub, cam_arg = cam_arg.lower(), None
    if sub:
        sub = sub.lower()

    cams = resolve_cam(cfg, cam_arg)

    for name, cam_info in cams.items():
        cam_id = cam_info["id"]
        print(f"\n── Rules: {name} ──────────────────────────────────────────────")

        if sub == "add":
            rule_name = getattr(args, "rule_name", None) or "New Rule"
            start     = getattr(args, "start", "00:00")
            end       = getattr(args, "end", "23:59")
            days_str  = getattr(args, "days", "0,1,2,3,4,5,6")
            weekdays  = [int(d.strip()) for d in days_str.split(",") if d.strip().isdigit()]

            body = {
                "id": None,
                "name": rule_name,
                "isActive": True,
                "startTime": f"{start}:00",
                "endTime": f"{end}:00",
                "weekdays": weekdays,
            }
            print(f"  ➕  Creating rule: {rule_name}")
            print(f"      Time: {start} → {end}  Days: {weekdays}")
            r = session.post(
                f"{CLOUD_API}/v11/video_inputs/{cam_id}/rules",
                json=body,
                headers={"Content-Type": "application/json"},
                timeout=10,
            )
            if r.status_code in (200, 201):
                data = r.json()
                rule_id = data.get("id", "(unknown)")
                print(f"  ✅  Rule created: id={rule_id}")
            elif r.status_code == 444:
                print(f"  ⚠️   Camera offline or unavailable for this operation")
                try:
                    print(f"       {r.json()}")
                except Exception:
                    print(f"       {r.text[:200]}")
            else:
                print(f"  ❌  Failed: HTTP {r.status_code}  {r.text[:200]}")
            continue

        if sub == "edit":
            rule_id = getattr(args, "rule_id", None)
            if not rule_id:
                print("  ❌  --id is required for edit. Usage: rules [cam] edit --id RULE_ID --active|--inactive")
                continue
            active = getattr(args, "active", False)
            inactive = getattr(args, "inactive", False)

            # Fetch current rule first
            r = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/rules", timeout=10)
            if r.status_code != 200:
                print(f"  ❌  Could not fetch rules: HTTP {r.status_code}")
                continue
            rules = r.json()
            target_rule = None
            for rule in rules:
                if rule.get("id") == rule_id:
                    target_rule = rule
                    break
            if not target_rule:
                print(f"  ❌  Rule ID '{rule_id}' not found.")
                continue

            if active:
                target_rule["isActive"] = True
            if inactive:
                target_rule["isActive"] = False
            # Allow changing name, times, and weekdays
            edit_name = getattr(args, "name", None)
            edit_start = getattr(args, "start", None)
            edit_end = getattr(args, "end", None)
            edit_days = getattr(args, "days", None)
            if edit_name:
                target_rule["name"] = edit_name
            if edit_start:
                target_rule["startTime"] = edit_start if len(edit_start.split(":")) == 3 else f"{edit_start}:00"
            if edit_end:
                target_rule["endTime"] = edit_end if len(edit_end.split(":")) == 3 else f"{edit_end}:00"
            if edit_days:
                target_rule["weekdays"] = [int(d.strip()) for d in edit_days.split(",")]

            print(f"  ✏️   Updating rule: {rule_id}")
            pr = session.put(
                f"{CLOUD_API}/v11/video_inputs/{cam_id}/rules/{rule_id}",
                json=target_rule,
                headers={"Content-Type": "application/json"},
                timeout=10,
            )
            if pr.status_code in (200, 201, 204):
                print(f"  ✅  Rule updated: isActive={target_rule.get('isActive')}")
            elif pr.status_code == 444:
                print(f"  ⚠️   Camera offline or unavailable for this operation")
                try:
                    print(f"       {pr.json()}")
                except Exception:
                    print(f"       {pr.text[:200]}")
            else:
                print(f"  ❌  Failed: HTTP {pr.status_code}  {pr.text[:200]}")
            continue

        if sub == "delete":
            rule_id = getattr(args, "rule_id", None)
            if not rule_id:
                print("  ❌  --id is required for delete. Usage: rules [cam] delete --id RULE_ID")
                continue
            print(f"  🗑️   Deleting rule: {rule_id}")
            r = session.delete(
                f"{CLOUD_API}/v11/video_inputs/{cam_id}/rules/{rule_id}",
                timeout=10,
            )
            if r.status_code in (200, 204):
                print(f"  ✅  Rule deleted.")
            elif r.status_code == 444:
                print(f"  ⚠️   Camera offline or unavailable for this operation")
                try:
                    print(f"       {r.json()}")
                except Exception:
                    print(f"       {r.text[:200]}")
            else:
                print(f"  ❌  Failed: HTTP {r.status_code}  {r.text[:200]}")
            continue

        # Default: list all rules
        r = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/rules", timeout=10)
        if r.status_code == 401:
            print("  ❌  Token expired.")
            return
        if r.status_code == 444:
            print(f"  ⚠️   Camera offline or unavailable for this operation")
            try:
                print(f"       {r.json()}")
            except Exception:
                print(f"       {r.text[:200]}")
            continue
        if r.status_code != 200:
            print(f"  ❌  Could not fetch rules: HTTP {r.status_code}")
            continue
        rules = r.json()
        if not rules:
            print(f"  (no rules configured)")
            print(f"\n  Create a rule with:")
            print(f"    python3 bosch_camera.py rules {name.lower()} add --name 'Night Mode' --start 22:00 --end 06:00 --days 0,1,2,3,4,5,6")
            continue
        print(f"  {len(rules)} rule(s):\n")
        DAY_NAMES = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
        for rule in rules:
            rid    = rule.get("id", "?")
            rname  = rule.get("name", "?")
            active = rule.get("isActive", False)
            start  = rule.get("startTime", "?")
            end    = rule.get("endTime", "?")
            days   = rule.get("weekdays", [])
            days_str = ", ".join(DAY_NAMES[d] if d < len(DAY_NAMES) else str(d) for d in days)
            icon   = "✅" if active else "⏸️"
            print(f"  {icon}  {rname}")
            print(f"      ID:     {rid}")
            print(f"      Active: {active}")
            print(f"      Time:   {start} → {end}")
            print(f"      Days:   {days_str}")
            print()


def cmd_friends(cfg: dict, args) -> None:
    """Manage camera sharing with friends.

    Usage:
      python3 bosch_camera.py friends                              → list all friends
      python3 bosch_camera.py friends invite EMAIL                 → invite a friend
      python3 bosch_camera.py friends share FRIEND_ID CAM [--days N]
      python3 bosch_camera.py friends unshare FRIEND_ID
      python3 bosch_camera.py friends resend FRIEND_ID
      python3 bosch_camera.py friends remove FRIEND_ID

    API: GET/POST/PUT/DELETE /v11/friends/*
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    sub     = getattr(args, "sub", None)
    sub_arg = getattr(args, "sub_arg", None)

    print(f"\n── Friends / Camera Sharing ─────────────────────────────────────")

    if sub == "invite":
        email = sub_arg
        if not email:
            print("  ❌  Email is required. Usage: friends invite EMAIL")
            return
        body = {"invitationEmail": email, "nickName": email}
        print(f"  📨  Inviting {email}...")
        r = session.post(
            f"{CLOUD_API}/v11/friends",
            json=body,
            headers={"Content-Type": "application/json"},
            timeout=10,
        )
        if r.status_code in (200, 201):
            data = r.json()
            print(f"  ✅  Invitation sent! Friend ID: {data.get('id', '(see response)')}")
            print(f"      {json.dumps(data, indent=2)}")
        elif r.status_code == 444:
            print(f"  ⚠️   Camera offline or unavailable for this operation")
            try:
                print(f"       {r.json()}")
            except Exception:
                print(f"       {r.text[:200]}")
        else:
            print(f"  ❌  Failed: HTTP {r.status_code}  {r.text[:200]}")
        return

    if sub == "share":
        friend_id = sub_arg
        cam_name  = getattr(args, "share_cam", None)
        days      = getattr(args, "days", None)
        if not friend_id or not cam_name:
            print("  ❌  Usage: friends share FRIEND_ID CAM [--days N]")
            return
        target_cams = resolve_cam(cfg, cam_name)
        if not target_cams:
            return
        shares = []
        for cname, cinfo in target_cams.items():
            share_entry = {"videoInputId": cinfo["id"]}
            if days:
                now = datetime.datetime.utcnow()
                end = now + datetime.timedelta(days=days)
                share_entry["shareTime"] = {
                    "start": now.strftime("%Y-%m-%dT%H:%M:%S.000Z"),
                    "end":   end.strftime("%Y-%m-%dT%H:%M:%S.000Z"),
                }
            shares.append(share_entry)

        print(f"  🔗  Sharing {len(shares)} camera(s) with friend {friend_id}...")
        r = session.put(
            f"{CLOUD_API}/v11/friends/{friend_id}/share",
            json=shares,
            headers={"Content-Type": "application/json"},
            timeout=10,
        )
        if r.status_code in (200, 201, 204):
            print(f"  ✅  Camera(s) shared!")
        elif r.status_code == 444:
            print(f"  ⚠️   Camera offline or unavailable for this operation")
            try:
                print(f"       {r.json()}")
            except Exception:
                print(f"       {r.text[:200]}")
        else:
            print(f"  ❌  Failed: HTTP {r.status_code}  {r.text[:200]}")
        return

    if sub == "unshare":
        friend_id = sub_arg
        if not friend_id:
            print("  ❌  Usage: friends unshare FRIEND_ID")
            return
        print(f"  🔓  Removing all camera shares from friend {friend_id}...")
        r = session.put(
            f"{CLOUD_API}/v11/friends/{friend_id}/share",
            json=[],
            headers={"Content-Type": "application/json"},
            timeout=10,
        )
        if r.status_code in (200, 201, 204):
            print(f"  ✅  All cameras unshared.")
        elif r.status_code == 444:
            print(f"  ⚠️   Camera offline or unavailable for this operation")
            try:
                print(f"       {r.json()}")
            except Exception:
                print(f"       {r.text[:200]}")
        else:
            print(f"  ❌  Failed: HTTP {r.status_code}  {r.text[:200]}")
        return

    if sub == "resend":
        friend_id = sub_arg
        if not friend_id:
            print("  ❌  Usage: friends resend FRIEND_ID")
            return
        print(f"  📨  Re-sending invitation to friend {friend_id}...")
        r = session.put(
            f"{CLOUD_API}/v11/friends/{friend_id}/resend_invite",
            json={"email": ""},
            headers={"Content-Type": "application/json"},
            timeout=10,
        )
        if r.status_code in (200, 201, 204):
            print(f"  ✅  Invitation re-sent!")
        elif r.status_code == 444:
            print(f"  ⚠️   Camera offline or unavailable for this operation")
            try:
                print(f"       {r.json()}")
            except Exception:
                print(f"       {r.text[:200]}")
        else:
            print(f"  ❌  Failed: HTTP {r.status_code}  {r.text[:200]}")
        return

    if sub == "remove":
        friend_id = sub_arg
        if not friend_id:
            print("  ❌  Usage: friends remove FRIEND_ID")
            return
        print(f"  🗑️   Removing friend {friend_id}...")
        r = session.delete(f"{CLOUD_API}/v11/friends/{friend_id}", timeout=10)
        if r.status_code in (200, 204):
            print(f"  ✅  Friend removed.")
        elif r.status_code == 444:
            print(f"  ⚠️   Camera offline or unavailable for this operation")
            try:
                print(f"       {r.json()}")
            except Exception:
                print(f"       {r.text[:200]}")
        else:
            print(f"  ❌  Failed: HTTP {r.status_code}  {r.text[:200]}")
        return

    # Default: list all friends
    r = session.get(f"{CLOUD_API}/v11/friends", timeout=10)
    if r.status_code == 401:
        print("  ❌  Token expired.")
        return
    if r.status_code == 444:
        print(f"  ⚠️   Camera offline or unavailable for this operation")
        try:
            print(f"       {r.json()}")
        except Exception:
            print(f"       {r.text[:200]}")
        return
    if r.status_code != 200:
        print(f"  ❌  Could not fetch friends: HTTP {r.status_code}")
        return
    friends = r.json()
    if not friends:
        print(f"  (no friends / camera shares)")
        print(f"\n  Invite a friend with:")
        print(f"    python3 bosch_camera.py friends invite user@example.com")
        return
    print(f"  {len(friends)} friend(s):\n")
    for friend in friends:
        fid    = friend.get("id", "?")
        email  = friend.get("email", friend.get("invitationEmail", "?"))
        nick   = friend.get("nickName", "?")
        status = friend.get("status", friend.get("invitationStatus", "?"))
        shares = friend.get("sharedVideoInputs", friend.get("shares", []))
        icon   = "✅" if status in ("ACCEPTED", "ACTIVE") else "⏳"
        print(f"  {icon}  {nick} ({email})")
        print(f"      ID:     {fid}")
        print(f"      Status: {status}")
        if shares:
            print(f"      Shared: {len(shares)} camera(s)")
            for sh in shares:
                vid = sh.get("videoInputId", "?")
                print(f"        • {vid}")
        print()


def cmd_accept_invite(cfg: dict, args) -> None:
    """Accept an incoming friend/camera sharing invitation.

    Usage:
      python3 bosch_camera.py accept-invite TOKEN

    API: POST /v11/friends/accept
    """
    token   = get_token(cfg)
    session = make_session(token)
    invite_token = getattr(args, "token", None)

    if not invite_token:
        print("  ❌  Invitation token is required. Usage: accept-invite TOKEN")
        return

    print(f"\n── Accept Friend Invitation ───────────────────────────────────")
    print(f"  📨  Accepting invitation...")

    r = session.post(
        f"{CLOUD_API}/v11/friends/accept",
        json={"token": invite_token},
        headers={"Content-Type": "application/json"},
        timeout=10,
    )
    if r.status_code in (200, 201, 204):
        print(f"  ✅  Invitation accepted!")
        try:
            data = r.json()
            print(f"      {json.dumps(data, indent=2)}")
        except Exception:
            pass
    elif r.status_code == 444:
        print(f"  ⚠️   Camera offline or unavailable for this operation")
        try:
            print(f"       {r.json()}")
        except Exception:
            print(f"       {r.text[:200]}")
    else:
        print(f"  ❌  Failed: HTTP {r.status_code}  {r.text[:200]}")


def cmd_shared_with_friends(cfg: dict, args) -> None:
    """Show which friends have access to a specific camera.

    Usage:
      python3 bosch_camera.py shared [cam-name]

    API: GET /v11/video_inputs/{id}/shared_with_friends
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cams    = resolve_cam(cfg, getattr(args, "cam", None))

    print(f"\n── Shared With Friends ────────────────────────────────────────")

    for cam_name, cam_info in cams.items():
        cam_id = cam_info["id"]
        model  = cam_info.get("hardwareVersion", "?")
        model_name = HW_DISPLAY_NAMES.get(model, model)
        print(f"\n  📷  {cam_name} ({model_name})")

        r = session.get(
            f"{CLOUD_API}/v11/video_inputs/{cam_id}/shared_with_friends",
            timeout=10,
        )
        if r.status_code == 200:
            friends = r.json()
            if not friends:
                print(f"      (not shared with anyone)")
                continue
            if isinstance(friends, list):
                print(f"      Shared with {len(friends)} friend(s):")
                for friend in friends:
                    fid    = friend.get("id", friend.get("friendId", "?"))
                    email  = friend.get("email", friend.get("invitationEmail", "?"))
                    nick   = friend.get("nickName", "?")
                    status = friend.get("status", friend.get("invitationStatus", "?"))
                    icon   = "✅" if status in ("ACCEPTED", "ACTIVE") else "⏳"
                    print(f"      {icon}  {nick} ({email})")
                    print(f"          ID:     {fid}")
                    print(f"          Status: {status}")
                    share_time = friend.get("shareTime", {})
                    if share_time:
                        print(f"          From:   {share_time.get('start', '?')}")
                        print(f"          Until:  {share_time.get('end', 'permanent')}")
            else:
                print(f"      {json.dumps(friends, indent=2)}")
        elif r.status_code == 444:
            print(f"      ⚠️   Camera offline or unavailable")
        else:
            print(f"      ❌  HTTP {r.status_code}  {r.text[:200]}")

    print()


def cmd_zones(cfg: dict, args) -> None:
    """Manage motion detection zones (cloud API).

    Usage:
      python3 bosch_camera.py zones [cam]                  → list current zones
      python3 bosch_camera.py zones [cam] set --json '[{"x":0.0,"y":0.3,"w":0.67,"h":0.7}]'
      python3 bosch_camera.py zones [cam] clear             → remove all zones

    API: GET/POST /v11/video_inputs/{id}/motion_sensitive_areas
    Coordinates: normalized 0.0–1.0 (x, y = top-left corner, w = width, h = height)
    Note: Returns HTTP 443 when privacy mode is active.
    """
    import json as _json
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cam_arg = getattr(args, "cam", None)
    sub     = getattr(args, "sub", None)

    ZONES_SUBS = ("set", "clear")
    if cam_arg and cam_arg.lower() in ZONES_SUBS and not sub:
        sub, cam_arg = cam_arg.lower(), None
    if sub:
        sub = sub.lower()

    cams = resolve_cam(cfg, cam_arg)

    for name, cam_info in cams.items():
        cam_id = cam_info["id"]
        print(f"\n── Motion Zones: {name} ──────────────────────────────────────")

        if sub == "set":
            zones_json = getattr(args, "json", None)
            if not zones_json:
                print("  ❌  --json is required. Example: --json '[{\"x\":0.0,\"y\":0.3,\"w\":0.67,\"h\":0.7}]'")
                continue
            try:
                zones = _json.loads(zones_json)
            except _json.JSONDecodeError as e:
                print(f"  ❌  Invalid JSON: {e}")
                continue
            if not isinstance(zones, list):
                print("  ❌  Zones must be a JSON array of objects with x, y, w, h")
                continue
            for i, z in enumerate(zones):
                for key in ("x", "y", "w", "h"):
                    if key not in z:
                        print(f"  ❌  Zone {i} missing '{key}'")
                        continue
            print(f"  ✏️   Setting {len(zones)} zone(s)...")
            r = session.post(
                f"{CLOUD_API}/v11/video_inputs/{cam_id}/motion_sensitive_areas",
                json=zones,
                headers={"Content-Type": "application/json"},
                timeout=10,
            )
            if r.status_code in (200, 204):
                print(f"  ✅  {len(zones)} zone(s) set.")
            elif r.status_code == 443:
                print(f"  ⚠️   Not available (HTTP 443) — privacy mode may be active.")
            else:
                print(f"  ❌  Failed: HTTP {r.status_code}  {r.text[:200]}")
            continue

        if sub == "clear":
            print(f"  🗑️   Clearing all zones...")
            r = session.post(
                f"{CLOUD_API}/v11/video_inputs/{cam_id}/motion_sensitive_areas",
                json=[],
                headers={"Content-Type": "application/json"},
                timeout=10,
            )
            if r.status_code in (200, 204):
                print(f"  ✅  All zones cleared.")
            elif r.status_code == 443:
                print(f"  ⚠️   Not available (HTTP 443) — privacy mode may be active.")
            else:
                print(f"  ❌  Failed: HTTP {r.status_code}  {r.text[:200]}")
            continue

        # Default: list zones
        r = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/motion_sensitive_areas", timeout=10)
        if r.status_code == 401:
            print("  ❌  Token expired.")
            return
        if r.status_code == 443:
            print(f"  ⚠️   Not available (HTTP 443) — privacy mode may be active.")
            continue
        if r.status_code != 200:
            print(f"  ❌  Could not fetch zones: HTTP {r.status_code}")
            continue
        zones = r.json()
        if not zones:
            print(f"  (no motion zones configured)")
            continue
        print(f"  {len(zones)} zone(s):\n")
        for i, z in enumerate(zones):
            print(f"  Zone {i+1}: x={z.get('x', 0):.4f}  y={z.get('y', 0):.4f}  w={z.get('w', 0):.4f}  h={z.get('h', 0):.4f}")
        print(f"\n  JSON: {_json.dumps(zones)}")


def cmd_privacy_masks(cfg: dict, args) -> None:
    """Manage privacy mask zones (cloud API).

    Usage:
      python3 bosch_camera.py privacy-masks [cam]                  → list current masks
      python3 bosch_camera.py privacy-masks [cam] set --json '[{"x":0.0,"y":0.0,"w":0.3,"h":0.3}]'
      python3 bosch_camera.py privacy-masks [cam] clear            → remove all masks

    API: GET/POST /v11/video_inputs/{id}/privacy_masks
    Coordinates: normalized 0.0–1.0 (x, y = top-left corner, w = width, h = height)
    Note: Returns HTTP 443 when privacy mode is active.
    """
    import json as _json
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cam_arg = getattr(args, "cam", None)
    sub     = getattr(args, "sub", None)

    MASKS_SUBS = ("set", "clear")
    if cam_arg and cam_arg.lower() in MASKS_SUBS and not sub:
        sub, cam_arg = cam_arg.lower(), None
    if sub:
        sub = sub.lower()

    cams = resolve_cam(cfg, cam_arg)

    for name, cam_info in cams.items():
        cam_id = cam_info["id"]
        print(f"\n── Privacy Masks: {name} ──────────────────────────────────────")

        if sub == "set":
            masks_json = getattr(args, "json", None)
            if not masks_json:
                print("  ❌  --json is required. Example: --json '[{\"x\":0.0,\"y\":0.0,\"w\":0.3,\"h\":0.3}]'")
                continue
            try:
                masks = _json.loads(masks_json)
            except _json.JSONDecodeError as e:
                print(f"  ❌  Invalid JSON: {e}")
                continue
            if not isinstance(masks, list):
                print("  ❌  Masks must be a JSON array of objects with x, y, w, h")
                continue
            print(f"  ✏️   Setting {len(masks)} mask(s)...")
            r = session.post(
                f"{CLOUD_API}/v11/video_inputs/{cam_id}/privacy_masks",
                json=masks,
                headers={"Content-Type": "application/json"},
                timeout=10,
            )
            if r.status_code in (200, 204):
                print(f"  ✅  {len(masks)} mask(s) set.")
            elif r.status_code == 443:
                print(f"  ⚠️   Not available (HTTP 443) — privacy mode may be active.")
            else:
                print(f"  ❌  Failed: HTTP {r.status_code}  {r.text[:200]}")
            continue

        if sub == "clear":
            print(f"  🗑️   Clearing all masks...")
            r = session.post(
                f"{CLOUD_API}/v11/video_inputs/{cam_id}/privacy_masks",
                json=[],
                headers={"Content-Type": "application/json"},
                timeout=10,
            )
            if r.status_code in (200, 204):
                print(f"  ✅  All masks cleared.")
            elif r.status_code == 443:
                print(f"  ⚠️   Not available (HTTP 443) — privacy mode may be active.")
            else:
                print(f"  ❌  Failed: HTTP {r.status_code}  {r.text[:200]}")
            continue

        # Default: list masks
        r = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/privacy_masks", timeout=10)
        if r.status_code == 401:
            print("  ❌  Token expired.")
            return
        if r.status_code == 443:
            print(f"  ⚠️   Not available (HTTP 443) — privacy mode may be active.")
            continue
        if r.status_code != 200:
            print(f"  ❌  Could not fetch masks: HTTP {r.status_code}")
            continue
        masks = r.json()
        if not masks:
            print(f"  (no privacy masks configured)")
            continue
        print(f"  {len(masks)} mask(s):\n")
        for i, m in enumerate(masks):
            print(f"  Mask {i+1}: x={m.get('x', 0):.4f}  y={m.get('y', 0):.4f}  w={m.get('w', 0):.4f}  h={m.get('h', 0):.4f}")
        print(f"\n  JSON: {_json.dumps(masks)}")


def cmd_lighting_schedule(cfg: dict, args) -> None:
    """View or modify the lighting schedule for cameras with LED light.

    Usage:
      python3 bosch_camera.py lighting-schedule [cam]      → show current schedule
      python3 bosch_camera.py lighting-schedule [cam] set --on HH:MM --off HH:MM [--motion] [--threshold 0.0-1.0]

    API: GET/PUT /v11/video_inputs/{id}/lighting_options
    Only available for outdoor cameras (Eyes) with LED light.
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cam_arg = getattr(args, "cam", None)
    sub     = getattr(args, "sub", None)

    if cam_arg and cam_arg.lower() == "set" and not sub:
        sub, cam_arg = "set", None
    if sub:
        sub = sub.lower()

    cams = resolve_cam(cfg, cam_arg)

    for name, cam_info in cams.items():
        cam_id = cam_info["id"]
        print(f"\n── Lighting Schedule: {name} ──────────────────────────────────")

        if sub == "set":
            # Fetch current first
            r = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/lighting_options", timeout=10)
            if r.status_code != 200:
                print(f"  ❌  Could not fetch: HTTP {r.status_code}")
                continue
            data = r.json()
            on_time = getattr(args, "on", None)
            off_time = getattr(args, "off", None)
            motion = getattr(args, "motion", None)
            threshold = getattr(args, "threshold", None)
            if on_time:
                data["generalLightOnTime"] = on_time if len(on_time.split(":")) == 3 else f"{on_time}:00"
            if off_time:
                data["generalLightOffTime"] = off_time if len(off_time.split(":")) == 3 else f"{off_time}:00"
            if motion is not None:
                data["lightOnMotion"] = motion
            if threshold is not None:
                data["darknessThreshold"] = float(threshold)
            data["scheduleStatus"] = "FOLLOW_SCHEDULE"
            print(f"  ✏️   Updating schedule...")
            pr = session.put(
                f"{CLOUD_API}/v11/video_inputs/{cam_id}/lighting_options",
                json=data,
                headers={"Content-Type": "application/json"},
                timeout=10,
            )
            if pr.status_code in (200, 204):
                print(f"  ✅  Schedule updated: {data.get('generalLightOnTime')} → {data.get('generalLightOffTime')}")
            elif pr.status_code == 444:
                print(f"  ⚠️   Camera offline.")
            else:
                print(f"  ❌  Failed: HTTP {pr.status_code}  {pr.text[:200]}")
            continue

        # Default: show schedule
        r = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/lighting_options", timeout=10)
        if r.status_code == 401:
            print("  ❌  Token expired.")
            return
        if r.status_code == 444:
            print(f"  ⚠️   Camera offline.")
            continue
        if r.status_code == 442:
            print(f"  ⚠️   Not supported on this camera model.")
            continue
        if r.status_code != 200:
            print(f"  ❌  HTTP {r.status_code}")
            continue
        d = r.json()
        print(f"  Modus:          {d.get('scheduleStatus', '?')}")
        print(f"  Zeitplan:       {d.get('generalLightOnTime', '?')} → {d.get('generalLightOffTime', '?')}")
        print(f"  Dunkelheit:     {d.get('darknessThreshold', '?')}")
        print(f"  Bei Bewegung:   {'Ja' if d.get('lightOnMotion') else 'Nein'} ({d.get('lightOnMotionFollowUpTimeSeconds', 0)}s Nachlauf)")
        print(f"  Frontlicht:     {'An' if d.get('frontIlluminatorInGeneralLightOn') else 'Aus'} (Intensität: {d.get('frontIlluminatorGeneralLightIntensity', '?')})")
        print(f"  Wallwasher:     {'An' if d.get('wallwasherInGeneralLightOn') else 'Aus'}")


def cmd_rename(cfg: dict, args) -> None:
    """Rename a camera via the Bosch cloud API.

    Usage:
      python3 bosch_camera.py rename CAM "New Name"

    API: PUT /v11/video_inputs
         Body: {"videoInputId": "uuid", "title": "New Name", "timeZone": "Europe/Berlin"}
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cam_arg = getattr(args, "cam", None)
    new_name = getattr(args, "new_name", None)

    if not cam_arg or not new_name:
        print("  ❌  Usage: rename CAM \"New Name\"")
        return

    cams = resolve_cam(cfg, cam_arg)
    if len(cams) != 1:
        print("  ❌  Rename requires exactly one camera.")
        return

    name, cam_info = next(iter(cams.items()))
    cam_id = cam_info["id"]

    print(f"\n── Rename Camera ──────────────────────────────────────────────")
    print(f"  📷  Camera:    {name}")
    print(f"  ✏️   New name:  {new_name}")

    body = {
        "videoInputId": cam_id,
        "title": new_name,
        "timeZone": "Europe/Berlin",
    }
    r = session.put(
        f"{CLOUD_API}/v11/video_inputs",
        json=body,
        headers={"Content-Type": "application/json"},
        timeout=10,
    )
    if r.status_code in (200, 201, 204):
        print(f"  ✅  Camera renamed to '{new_name}'.")
        # Update local config
        old_name = name
        cam_info["name"] = new_name
        cfg["cameras"][new_name] = cam_info
        if old_name != new_name and old_name in cfg["cameras"]:
            del cfg["cameras"][old_name]
        save_config(cfg)
        print(f"  💾  Config updated.")
    elif r.status_code == 444:
        print(f"  ⚠️   Camera offline or unavailable for this operation")
        try:
            print(f"       {r.json()}")
        except Exception:
            print(f"       {r.text[:200]}")
    else:
        print(f"  ❌  Failed: HTTP {r.status_code}  {r.text[:200]}")


def cmd_profile(cfg: dict, args) -> None:
    """Show or edit user profile.

    Usage:
      python3 bosch_camera.py profile                                → show user info
      python3 bosch_camera.py profile edit --display-name NAME --marketing on|off

    API: GET /v11/registration/check, PUT /v11/registration
    """
    token   = get_token(cfg)
    session = make_session(token)
    edit    = getattr(args, "sub", None)
    display_name = getattr(args, "display_name", None)
    marketing    = getattr(args, "marketing", None)

    # Allow "profile edit" without the sub argument
    if edit and edit.lower() == "edit":
        edit = "edit"
    elif edit:
        edit = None

    print(f"\n── User Profile ───────────────────────────────────────────────")

    # Fetch current profile
    r = session.get(f"{CLOUD_API}/v11/registration/check", timeout=10)
    if r.status_code == 401:
        print("  ❌  Token expired.")
        return
    if r.status_code == 444:
        print(f"  ⚠️   Camera offline or unavailable for this operation")
        try:
            print(f"       {r.json()}")
        except Exception:
            print(f"       {r.text[:200]}")
        return
    if r.status_code != 200:
        print(f"  ❌  Could not fetch profile: HTTP {r.status_code}  {r.text[:200]}")
        return
    data = r.json()
    # Response has nested "userInformation" object
    user_info  = data.get("userInformation", data)

    # Display profile info
    email      = user_info.get("email", "?")
    first      = user_info.get("firstName", "")
    last       = user_info.get("lastName", "")
    display    = user_info.get("displayName", "?")
    name       = f"{first} {last}".strip() if first else display
    last_login = data.get("lastLoginTime", "?")
    token_exp  = data.get("tokenExpirationTime", "?")
    mkt        = user_info.get("marketingContact", "?")
    iot        = user_info.get("iotThingsIntegration", "?")
    lang       = user_info.get("language", "?")
    tz         = user_info.get("timeZone", "?")
    problems   = data.get("loginProblems", [])

    print(f"  👤  Name:           {name} (display: {display})")
    print(f"  📧  Email:          {email}")
    print(f"  🌍  Language:       {lang}  /  Timezone: {tz}")
    print(f"  🕐  Last login:     {last_login}")
    print(f"  🔑  Token expires:  {token_exp}")
    print(f"  📢  Marketing:      {'✅ yes' if mkt is True else '❌ no' if mkt is False else mkt}")
    print(f"  🏠  IoT integration: {'✅ yes' if iot is True else '❌ no' if iot is False else iot}")
    if problems:
        print(f"  ⚠️   Login problems: {problems}")

    # Show token age from local config
    print(f"  🔐  Local token:    {check_token_age(cfg)}")

    # Show full response for debugging
    for key, val in data.items():
        if key not in ("userInformation", "lastLoginTime", "tokenExpirationTime", "loginProblems",
                        "userInformation", "lastLoginTime", "tokenExpirationTime", "loginProblems"):
            print(f"  ℹ️   {key}: {val}")

    if edit != "edit":
        print(f"\n  Edit with: python3 bosch_camera.py profile edit --display-name 'Name' --marketing on|off")
        return

    # Edit profile — build body from current profile + changes
    body = {
        "firstName": user_info.get("firstName", ""),
        "lastName": user_info.get("lastName", ""),
        "language": user_info.get("language", "de_DE"),
        "locale": user_info.get("locale", "de_DE"),
        "displayName": user_info.get("displayName", ""),
        "marketingContact": user_info.get("marketingContact", False),
        "iotThingsIntegration": user_info.get("iotThingsIntegration", True),
    }
    changed = False
    if display_name:
        body["displayName"] = display_name
        changed = True
    if marketing:
        body["marketingContact"] = marketing.lower() == "on"
        changed = True

    if not changed:
        print("\n  ⚠️   No changes specified. Use --display-name and/or --marketing.")
        return

    print(f"\n  🔄  Updating profile: {body}")
    pr = session.put(
        f"{CLOUD_API}/v11/registration",
        json=body,
        headers={"Content-Type": "application/json"},
        timeout=10,
    )
    if pr.status_code in (200, 201, 204):
        print(f"  ✅  Profile updated.")
    elif pr.status_code == 444:
        print(f"  ⚠️   Camera offline or unavailable for this operation")
        try:
            print(f"       {pr.json()}")
        except Exception:
            print(f"       {pr.text[:200]}")
    else:
        print(f"  ❌  Failed: HTTP {pr.status_code}  {pr.text[:200]}")


def cmd_account(cfg: dict, args) -> None:
    """Show account info: feature flags, contracts, subscription status.

    Usage:
      python3 bosch_camera.py account

    API: GET /v11/feature_flags, GET /v11/contracts, GET /v11/purchases
    """
    token   = get_token(cfg)
    session = make_session(token)

    print(f"\n── Account Info ───────────────────────────────────────────────")

    # Feature flags
    print(f"\n  ── Feature Flags ──────────────────────────────────────────────")
    r = session.get(f"{CLOUD_API}/v11/feature_flags", timeout=10)
    if r.status_code == 200:
        flags = r.json()
        if isinstance(flags, dict):
            for key, val in flags.items():
                icon = "✅" if val else "❌"
                print(f"  {icon}  {key}: {val}")
        elif isinstance(flags, list):
            for flag in flags:
                if isinstance(flag, dict):
                    fname = flag.get("name", flag.get("key", "?"))
                    fval  = flag.get("value", flag.get("enabled", "?"))
                    icon  = "✅" if fval else "❌"
                    print(f"  {icon}  {fname}: {fval}")
                else:
                    print(f"  ✅  {flag}")
        else:
            print(f"  {json.dumps(flags, indent=2)}")
    elif r.status_code == 444:
        print(f"  ⚠️   Camera offline or unavailable for this operation")
    else:
        print(f"  ⚠️   Feature flags: HTTP {r.status_code}")

    # Contracts (T&C versions)
    print(f"\n  ── Contracts / Terms ──────────────────────────────────────────")
    r = session.get(f"{CLOUD_API}/v11/contracts", params={"locale": "de_DE"}, timeout=10)
    if r.status_code == 200:
        contracts = r.json()
        if isinstance(contracts, dict):
            tac_ver = contracts.get("tacVersion", "?")
            tac_url = contracts.get("tacURL", "?")
            dpn_ver = contracts.get("dpnVersion", "?")
            dpn_url = contracts.get("dpnURL", "?")
            print(f"  📄  Terms & Conditions: {tac_ver}")
            print(f"     {tac_url}")
            print(f"  🔒  Data Protection:    {dpn_ver}")
            print(f"     {dpn_url}")
        elif isinstance(contracts, list):
            for c in contracts:
                print(f"  📄  {json.dumps(c)}")
        else:
            print(f"  {contracts}")
    elif r.status_code == 444:
        print(f"  ⚠️   Camera offline or unavailable for this operation")
    else:
        print(f"  ⚠️   Contracts: HTTP {r.status_code}")

    # Purchases / subscription
    print(f"\n  ── Purchases / Subscriptions ──────────────────────────────────")
    r = session.get(f"{CLOUD_API}/v11/purchases", timeout=10)
    if r.status_code == 200:
        purchases = r.json()
        if isinstance(purchases, list):
            if not purchases:
                print(f"  (no active purchases/subscriptions)")
            for p in purchases:
                pname   = p.get("name", p.get("productId", "?"))
                pstatus = p.get("status", p.get("state", "?"))
                pexpiry = p.get("expiryDate", p.get("validUntil", "?"))
                icon    = "✅" if pstatus in ("ACTIVE", "active") else "⏸️"
                print(f"  {icon}  {pname}")
                print(f"      Status: {pstatus}")
                if pexpiry and pexpiry != "?":
                    print(f"      Expires: {pexpiry}")
        elif isinstance(purchases, dict):
            print(f"  {json.dumps(purchases, indent=2)}")
        else:
            print(f"  {purchases}")
    elif r.status_code == 444:
        print(f"  ⚠️   Camera offline or unavailable for this operation")
    else:
        print(f"  ⚠️   Purchases: HTTP {r.status_code}")

    print()


def cmd_timestamp(cfg: dict, args) -> None:
    """Get or set time/date overlay on camera video.

    Usage:
      python3 bosch_camera.py timestamp [cam-name]        → show current state
      python3 bosch_camera.py timestamp [cam-name] on     → enable timestamp overlay
      python3 bosch_camera.py timestamp [cam-name] off    → disable timestamp overlay

    API: GET/PUT /v11/video_inputs/{id}/timestamp
         Body: {"result": true/false}
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cam_arg = getattr(args, "cam", None)
    action  = getattr(args, "action", None)

    if cam_arg and cam_arg.lower() in ("on", "off") and action is None:
        action  = cam_arg.lower()
        cam_arg = None

    cams = resolve_cam(cfg, cam_arg)

    for name, cam_info in cams.items():
        cam_id = cam_info["id"]
        print(f"\n── Timestamp Overlay: {name} ─────────────────────────────────────")

        r = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/timestamp", timeout=10)
        if r.status_code == 401:
            print("  ❌  Token expired.")
            return
        if r.status_code == 444:
            print(f"  ⚠️   Camera offline or unavailable")
            continue
        if r.status_code != 200:
            print(f"  ❌  Could not fetch timestamp state: HTTP {r.status_code}")
            continue
        data    = r.json()
        current = data.get("result", False)
        icon    = "🕐" if current else "🕐"
        print(f"  {icon}  Timestamp overlay:  {'ENABLED' if current else 'DISABLED'}")

        if action is None:
            print(f"\n  Run with 'on' or 'off' to toggle. E.g.:")
            print(f"    python3 bosch_camera.py timestamp {name.lower()} on")
            continue

        new_state = action == "on"
        if new_state == current:
            print(f"  ✅  Already {'ENABLED' if current else 'DISABLED'} — no change needed.")
            continue

        print(f"  🔄  Setting timestamp overlay → {'ENABLED' if new_state else 'DISABLED'}...")
        pr = session.put(
            f"{CLOUD_API}/v11/video_inputs/{cam_id}/timestamp",
            json={"result": new_state},
            headers={"Content-Type": "application/json"},
            timeout=10,
        )
        if pr.status_code in (200, 201, 204):
            print(f"  ✅  Timestamp overlay {'ENABLED' if new_state else 'DISABLED'}.")
        elif pr.status_code == 444:
            print(f"  ⚠️   Camera offline or unavailable")
        else:
            print(f"  ❌  Failed: HTTP {pr.status_code}  {pr.text[:200]}")


def cmd_notification_types(cfg: dict, args) -> None:
    """Show or toggle per-type notification settings.

    Usage:
      python3 bosch_camera.py notification-types [cam-name]
      python3 bosch_camera.py notification-types [cam-name] --set movement=on person=off

    API: GET/PUT /v11/video_inputs/{id}/notifications
    """
    token   = get_token(cfg)
    session = make_session(token)
    cameras = get_cameras(cfg, session)
    cam_arg = getattr(args, "cam", None)
    sets    = getattr(args, "set", None)

    cams = resolve_cam(cfg, cam_arg)

    for name, cam_info in cams.items():
        cam_id = cam_info["id"]
        print(f"\n── Notification Types: {name} ─────────────────────────────────────")

        r = session.get(f"{CLOUD_API}/v11/video_inputs/{cam_id}/notifications", timeout=10)
        if r.status_code == 401:
            print("  ❌  Token expired.")
            return
        if r.status_code == 444:
            print(f"  ⚠️   Camera offline or unavailable")
            continue
        if r.status_code != 200:
            print(f"  ❌  Could not fetch notification types: HTTP {r.status_code}")
            continue
        data = r.json()
        for key, val in sorted(data.items()):
            icon = "✅" if val else "❌"
            print(f"  {icon}  {key}: {'ON' if val else 'OFF'}")

        if not sets:
            print(f"\n  Toggle with: --set movement=on person=off audio=on")
            continue

        # Parse --set pairs
        for pair in sets:
            key, _, val_str = pair.partition("=")
            if val_str.lower() in ("on", "true", "1"):
                data[key] = True
            elif val_str.lower() in ("off", "false", "0"):
                data[key] = False
            else:
                print(f"  ⚠️   Invalid value for {key}: {val_str} (use on/off)")
                continue

        print(f"\n  🔄  Updating notification types...")
        pr = session.put(
            f"{CLOUD_API}/v11/video_inputs/{cam_id}/notifications",
            json=data,
            headers={"Content-Type": "application/json"},
            timeout=10,
        )
        if pr.status_code in (200, 201, 204):
            print(f"  ✅  Notification types updated.")
            for key, val in sorted(data.items()):
                icon = "✅" if val else "❌"
                print(f"  {icon}  {key}: {'ON' if val else 'OFF'}")
        else:
            print(f"  ❌  Failed: HTTP {pr.status_code}  {pr.text[:200]}")


def main():
    # ── Top-level parser ───────────────────────────────────────────────────────
    parser = argparse.ArgumentParser(
        prog="bosch_camera.py",
        description=(
            "📷  Bosch Smart Home Camera — standalone control tool  v" + VERSION + "\n"
            "    Full cloud API access: snapshots, live stream, events, camera controls."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "────────────────────────────────────────────────────────────────\n"
            "  Run WITHOUT arguments to open the interactive menu.\n"
            "  Use '<command> --help' for per-command details.\n"
            "\n"
            "  Examples:\n"
            "    python3 bosch_camera.py                          # interactive menu\n"
            "    python3 bosch_camera.py status\n"
            "    python3 bosch_camera.py snapshot Garten\n"
            "    python3 bosch_camera.py snapshot Garten --live\n"
            "    python3 bosch_camera.py live Kamera --vlc\n"
            "    python3 bosch_camera.py download Garten --clips-only --limit 20\n"
            "    python3 bosch_camera.py privacy Garten on --minutes 30\n"
            "    python3 bosch_camera.py pan Kamera right\n"
            "    python3 bosch_camera.py pan Kamera 45\n"
            "    python3 bosch_camera.py token fix\n"
        ),
    )

    subparsers = parser.add_subparsers(dest="command", metavar="<command>")

    # ── status ─────────────────────────────────────────────────────────────────
    subparsers.add_parser(
        "status",
        help="Show all cameras with ONLINE/OFFLINE status",
        description=(
            "📶  status — Camera list with ONLINE/OFFLINE status\n"
            "\n"
            "  Pings every known camera via the cloud API and prints\n"
            "  name, model, firmware version, MAC address and status."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="  Example:\n    python3 bosch_camera.py status",
    )

    # ── info ───────────────────────────────────────────────────────────────────
    p_info = subparsers.add_parser(
        "info",
        help="Full camera details + live stream URLs",
        description=(
            "ℹ️   info — Full camera details + live stream URLs\n"
            "\n"
            "  Fetches the complete camera object from the cloud API:\n"
            "  privacy mode, recording state, notifications, features,\n"
            "  WiFi signal, and the live RTSPS/snap URLs.\n"
            "\n"
            "  With --full: also queries 6 extra endpoints\n"
            "  (firmware, motion, audio alarm, lighting override,\n"
            "   recording options, ambient light sensor)."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py info\n"
            "    python3 bosch_camera.py info --full"
        ),
    )
    p_info.add_argument(
        "--full",
        action="store_true",
        help="Also fetch extra endpoints: firmware, motion, audio alarm, ambient light, WiFi",
    )

    # ── snapshot ───────────────────────────────────────────────────────────────
    p_snap = subparsers.add_parser(
        "snapshot",
        help="Save + open a camera snapshot",
        description=(
            "📸  snapshot — Save and open a camera snapshot\n"
            "\n"
            "  Default (no --live): fetches the latest motion-triggered\n"
            "  event snapshot from the cloud events API.\n"
            "\n"
            "  With --live: tries real-time methods in order:\n"
            "    1. Cloud proxy live snap  (~1.5 s, no credentials needed)\n"
            "    2. Local camera snap.jpg  (LAN, requires local_ip + creds in config)\n"
            "    3. Latest event snapshot  (fallback)\n"
            "\n"
            "  Aliases: liveshot / livesnap / live-snapshot  (imply --live)"
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py snapshot\n"
            "    python3 bosch_camera.py snapshot Garten\n"
            "    python3 bosch_camera.py snapshot Garten --live\n"
            "    python3 bosch_camera.py liveshot Kamera"
        ),
    )
    p_snap.add_argument(
        "cam",
        nargs="?",
        metavar="<camera>",
        help="Camera name or partial match (omit = all cameras)",
    )
    p_snap.add_argument(
        "--live",
        action="store_true",
        help="Prefer live snapshot methods (cloud proxy or local LAN) over event snapshot",
    )
    p_snap.add_argument(
        "--hq",
        action="store_true",
        help="Request highQualityVideo=true in PUT /connection (higher resolution)",
    )
    p_snap.add_argument(
        "--quality",
        choices=["auto", "high", "low"],
        metavar="Q",
        help="Quality preset: auto (default) | high (highQualityVideo=true) | low",
    )

    # ── liveshot aliases ───────────────────────────────────────────────────────
    for _alias in ("liveshot", "livesnap", "live-snapshot"):
        p_alias = subparsers.add_parser(
            _alias,
            help=f"Alias for 'snapshot --live'",
            description=f"📸  {_alias} — Alias for: snapshot --live\n\nSee 'snapshot --help' for full details.",
            formatter_class=argparse.RawDescriptionHelpFormatter,
        )
        p_alias.add_argument("cam", nargs="?", metavar="<camera>",
                             help="Camera name or partial match")
        p_alias.add_argument("--live", action="store_true", help=argparse.SUPPRESS)

    # ── live ───────────────────────────────────────────────────────────────────
    p_live = subparsers.add_parser(
        "live",
        help="Open live audio+video stream (ffplay / VLC)",
        description=(
            "📺  live — Open live audio+video stream\n"
            "\n"
            "  Opens an RTSPS stream (H.264 1920×1080 30fps + AAC audio)\n"
            "  via the Bosch cloud proxy (port 443, TLS).\n"
            "\n"
            "  Default player: ffplay (recommended — supports TLS cert skip).\n"
            "  --vlc: pipes the stream through ffmpeg → VLC stdin (macOS only).\n"
            "\n"
            "  Alias: stream\n"
            "\n"
            "  Requirements:\n"
            "    brew install ffmpeg      # for ffplay (default)\n"
            "    brew install --cask vlc  # for --vlc mode"
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py live\n"
            "    python3 bosch_camera.py live Kamera\n"
            "    python3 bosch_camera.py live Garten --vlc"
        ),
    )
    p_live.add_argument(
        "cam",
        nargs="?",
        metavar="<camera>",
        help="Camera name or partial match (omit = first camera)",
    )
    p_live.add_argument(
        "--vlc",
        action="store_true",
        help="Open in VLC via ffmpeg pipe instead of ffplay (macOS only)",
    )
    p_live.add_argument(
        "--hq",
        action="store_true",
        help="Request highQualityVideo=true in PUT /connection (higher bitrate stream)",
    )
    p_live.add_argument(
        "--inst",
        type=int,
        default=2,
        metavar="N",
        help="Stream instance number in RTSPS URL (default: 2)",
    )
    p_live.add_argument(
        "--quality",
        choices=["auto", "high", "low"],
        metavar="Q",
        help="Quality preset: auto (inst=2, default) | high (inst=1, 30Mbps) | low (inst=4, 1.9Mbps)",
    )
    p_live.add_argument(
        "--local",
        action="store_true",
        help="Force LOCAL connection type (direct LAN stream with credentials)",
    )

    # ── test-local ─────────────────────────────────────────────────────────────
    p_testlocal = subparsers.add_parser(
        "test-local",
        help="Test LOCAL vs REMOTE connection — full response dump + snap timing + RTSP URL",
        description=(
            "🔬  test-local — Test LOCAL vs REMOTE connection\n"
            "\n"
            "  Calls PUT /connection with both LOCAL and REMOTE types and prints:\n"
            "    • Full raw JSON response (user, password, urls, imageUrlScheme, ...)\n"
            "    • snap.jpg HTTP status + timing\n"
            "    • RTSPS URL to try manually in VLC or ffplay\n"
            "\n"
            "  Use this to verify LOCAL streaming works and diagnose the 15s startup issue.\n"
            "  Add --play to immediately open the LOCAL stream in ffplay."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    p_testlocal.add_argument("cam", nargs="?", metavar="<camera>",
                             help="Camera name or partial match (omit = first camera)")
    p_testlocal.add_argument("--play", action="store_true",
                             help="Open LOCAL RTSPS stream in ffplay after testing")

    # stream alias
    p_stream = subparsers.add_parser(
        "stream",
        help="Alias for 'live'",
        description="📺  stream — Alias for: live\n\nSee 'live --help' for full details.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    p_stream.add_argument("cam", nargs="?", metavar="<camera>",
                          help="Camera name or partial match")
    p_stream.add_argument("--vlc", action="store_true",
                          help="Open in VLC via ffmpeg pipe instead of ffplay")
    p_stream.add_argument("--hq", action="store_true",
                          help="Request highQualityVideo=true in PUT /connection")
    p_stream.add_argument("--inst", type=int, default=2, metavar="N",
                          help="Stream instance number in RTSPS URL (default: 2)")
    p_stream.add_argument("--quality", choices=["auto", "high", "low"], metavar="Q",
                          help="Quality preset: auto | high (30Mbps) | low (1.9Mbps)")

    # "download" and "events" subcommands removed (Bosch request)

    # ── privacy ────────────────────────────────────────────────────────────────
    p_priv = subparsers.add_parser(
        "privacy",
        help="Show or toggle privacy mode (cloud API, no SHC needed)",
        description=(
            "🔒  privacy — Show or toggle privacy mode\n"
            "\n"
            "  Uses the Bosch cloud API directly — no SHC local API needed.\n"
            "  API: PUT /v11/video_inputs/{id}/privacy\n"
            "\n"
            "  States:\n"
            "    ON  — camera is blocked, no live images available\n"
            "    OFF — camera is active, live images available\n"
            "\n"
            "  With --minutes: sets a timed privacy period (auto-expires)."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py privacy                    # show all\n"
            "    python3 bosch_camera.py privacy Garten             # show one\n"
            "    python3 bosch_camera.py privacy on                 # ON (all cameras)\n"
            "    python3 bosch_camera.py privacy Garten on\n"
            "    python3 bosch_camera.py privacy Garten off\n"
            "    python3 bosch_camera.py privacy Garten on --minutes 30"
        ),
    )
    p_priv.add_argument(
        "cam",
        nargs="?",
        metavar="<camera>",
        help="Camera name or partial match (omit = all cameras)",
    )
    p_priv.add_argument(
        "action",
        nargs="?",
        metavar="on|off",
        choices=["on", "off"],
        help="Set privacy mode: on or off",
    )
    p_priv.add_argument(
        "--minutes",
        type=int,
        default=None,
        metavar="N",
        help="(with 'on') Enable privacy for N minutes, then auto-disable",
    )

    # ── light ──────────────────────────────────────────────────────────────────
    p_light = subparsers.add_parser(
        "light",
        help="Show or toggle camera light manual override (outdoor camera only)",
        description=(
            "💡  light — Show or toggle camera light manual override\n"
            "\n"
            "  Controls the built-in LED/wallwasher light of outdoor cameras.\n"
            "  Only available for cameras with featureSupport.light = true.\n"
            "  Uses the Bosch cloud API — no SHC local API needed.\n"
            "  API: PUT /v11/video_inputs/{id}/lighting_override\n"
            "\n"
            "  Shows current schedule mode, intensity, and motion-triggered\n"
            "  light settings when called without on/off."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py light                  # show all\n"
            "    python3 bosch_camera.py light Garten           # show one\n"
            "    python3 bosch_camera.py light on               # ON (all cameras)\n"
            "    python3 bosch_camera.py light Garten on\n"
            "    python3 bosch_camera.py light Garten off"
        ),
    )
    p_light.add_argument(
        "cam",
        nargs="?",
        metavar="<camera>",
        help="Camera name or partial match (omit = all cameras)",
    )
    p_light.add_argument(
        "action",
        nargs="?",
        metavar="on|off",
        choices=["on", "off"],
        help="Turn light override on or off",
    )

    # ── notifications ──────────────────────────────────────────────────────────
    p_notif = subparsers.add_parser(
        "notifications",
        help="Show or toggle push notifications (cloud API)",
        description=(
            "🔔  notifications — Show or toggle push notifications\n"
            "\n"
            "  Uses the Bosch cloud API.\n"
            "  API: PUT /v11/video_inputs/{id}/enable_notifications\n"
            "\n"
            "  States:\n"
            "    on  → FOLLOW_CAMERA_SCHEDULE (follows app schedule)\n"
            "    off → ALWAYS_OFF"
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py notifications\n"
            "    python3 bosch_camera.py notifications Garten\n"
            "    python3 bosch_camera.py notifications on\n"
            "    python3 bosch_camera.py notifications Garten off"
        ),
    )
    p_notif.add_argument(
        "cam",
        nargs="?",
        metavar="<camera>",
        help="Camera name or partial match (omit = all cameras)",
    )
    p_notif.add_argument(
        "action",
        nargs="?",
        metavar="on|off",
        choices=["on", "off"],
        help="Enable or disable push notifications",
    )

    # ── pan ────────────────────────────────────────────────────────────────────
    p_pan = subparsers.add_parser(
        "pan",
        help="Pan the 360 indoor camera (±120°)",
        description=(
            "↔️   pan — Pan the 360 indoor camera\n"
            "\n"
            "  Controls the pan position of the indoor 360 camera.\n"
            "  Only available for cameras with featureSupport.panLimit > 0.\n"
            "  API: PUT /v11/video_inputs/{id}/pan\n"
            "       Body: {\"absolutePosition\": <degrees>}\n"
            "\n"
            "  Presets:\n"
            "    left   →  -120° (full left)\n"
            "    center →    0°  (center)\n"
            "    right  → +120°  (full right)\n"
            "\n"
            "  Or pass any integer in range -panLimit to +panLimit."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py pan                    # show position\n"
            "    python3 bosch_camera.py pan Kamera             # show position\n"
            "    python3 bosch_camera.py pan left               # full left\n"
            "    python3 bosch_camera.py pan Kamera center\n"
            "    python3 bosch_camera.py pan Kamera right\n"
            "    python3 bosch_camera.py pan Kamera 45\n"
            "    python3 bosch_camera.py pan Kamera -90"
        ),
    )
    p_pan.add_argument(
        "cam",
        nargs="?",
        metavar="<camera>",
        help="Camera name or partial match (omit = all 360 cameras)",
    )
    p_pan.add_argument(
        "action",
        nargs="?",
        metavar="left|center|right|<degrees>",
        help="Target position: preset (left/center/right) or angle in degrees",
    )

    # ── token ──────────────────────────────────────────────────────────────────
    p_tok = subparsers.add_parser(
        "token",
        help="Show token status and optionally renew",
        description=(
            "🔑  token — Show OAuth2 token status and optionally renew\n"
            "\n"
            "  Decodes the JWT access token and shows expiry time,\n"
            "  account email, and refresh token status.\n"
            "\n"
            "  Actions:\n"
            "    fix      → renew silently via refresh_token (or browser if needed)\n"
            "    refresh  → same as fix\n"
            "    browser  → force a new browser login (ignores saved refresh_token)\n"
            "\n"
            "  The refresh_token enables silent renewal indefinitely\n"
            "  (set up once via: python3 get_token.py)."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py token\n"
            "    python3 bosch_camera.py token fix\n"
            "    python3 bosch_camera.py token browser"
        ),
    )
    p_tok.add_argument(
        "cam",
        nargs="?",
        metavar="fix|refresh|browser",
        help="Action: 'fix' or 'refresh' = silent renewal; 'browser' = force login",
    )

    # ── config ─────────────────────────────────────────────────────────────────
    subparsers.add_parser(
        "config",
        help="Show current config file (tokens masked)",
        description=(
            "⚙️   config — Show current config file\n"
            "\n"
            "  Prints bosch_config.json with tokens truncated for security.\n"
            "  Also shows the current token expiry."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="  Example:\n    python3 bosch_camera.py config",
    )

    # ── rcp ────────────────────────────────────────────────────────────────────
    p_rcp = subparsers.add_parser(
        "rcp",
        help="RCP protocol reads via cloud proxy (info, clock, snapshot, alarms, bitrate, ...)",
        description=(
            "🔌  rcp — Remote Configuration Protocol reads via cloud proxy\n"
            "\n"
            "  Opens a REMOTE proxy connection automatically, performs the RCP\n"
            "  session handshake, then reads the requested data.\n"
            "\n"
            "  The proxy hash acts as the credential — no extra auth needed.\n"
            "  Auth level = 3 (read-only). Writes require level 5 (not accessible\n"
            "  via cloud proxy).\n"
            "\n"
            "  Subcommands:\n"
            "    info      — identity: MAC, product name, FQDN, LAN IP\n"
            "    clock     — real-time camera clock (0x0a0f)\n"
            "    snapshot  — RCP JPEG thumbnail 160x90 (0x099e) — save + open\n"
            "    alarms    — alarm catalog from 0x0c38 (UTF-16-BE parsed)\n"
            "    privacy   — privacy mask state read (0x0d00 byte[1])\n"
            "    dimmer    — LED dimmer value 0-100 (0x0c22 T_WORD)\n"
            "    motion    — motion zones from 0x0c0a (count + coords)\n"
            "    services  — network services list from 0x0c62\n"
            "    frame     — raw video frame (0x0c98, 320x180 YUV422 -> JPEG)\n"
            "    script    — IVA automation script (0x09f3, gzip -> text)\n"
            "    iva       — IVA rule types + resiMotion config (0x0ba9 + 0x0a1b)\n"
            "    bitrate   — bitrate ladder tiers in kbps (0x0c81)\n"
            "    all       — run all of the above"
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py rcp info\n"
            "    python3 bosch_camera.py rcp Garten info\n"
            "    python3 bosch_camera.py rcp Kamera clock\n"
            "    python3 bosch_camera.py rcp Garten snapshot\n"
            "    python3 bosch_camera.py rcp Garten bitrate\n"
            "    python3 bosch_camera.py rcp all\n"
            "    python3 bosch_camera.py rcp Garten all"
        ),
    )
    p_rcp.add_argument(
        "cam",
        nargs="?",
        metavar="<camera>",
        help="Camera name or partial match (omit = all cameras)",
    )
    p_rcp.add_argument(
        "sub",
        nargs="?",
        metavar="info|clock|snapshot|alarms|privacy|dimmer|motion|services|frame|script|iva|bitrate|all",
        help="RCP subcommand to run",
    )

    # ── rescan ─────────────────────────────────────────────────────────────────
    subparsers.add_parser(
        "rescan",
        help="Re-discover cameras from API and update config",
        description=(
            "🔍  rescan — Re-discover cameras\n"
            "\n"
            "  Calls GET /v11/video_inputs, updates the cameras section\n"
            "  in bosch_config.json, and optionally prompts for local IPs."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="  Example:\n    python3 bosch_camera.py rescan",
    )

    # ── watch ──────────────────────────────────────────────────────────────────
    p_watch = subparsers.add_parser(
        "watch",
        help="Poll for new events in real-time",
        description=(
            "👁️   watch — Poll for new camera events in real-time\n"
            "\n"
            "  Polls GET /v11/events every N seconds (default 30) and prints\n"
            "  any new events as they arrive. Runs until Ctrl+C or --duration\n"
            "  seconds elapsed.\n"
            "\n"
            "  Each new event shows: time, type (MOVEMENT / AUDIO_ALARM),\n"
            "  camera name, timestamp, snapshot URL, and clip URL."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py watch\n"
            "    python3 bosch_camera.py watch Garten\n"
            "    python3 bosch_camera.py watch Garten --interval 15\n"
            "    python3 bosch_camera.py watch --duration 600\n"
            "    python3 bosch_camera.py watch Garten --snapshot   # auto-open JPEG on new event"
        ),
    )
    p_watch.add_argument("cam", nargs="?", help="Camera name (optional, all cameras if omitted)")
    p_watch.add_argument("--interval", type=int, default=30, metavar="N",
                         help="Poll interval in seconds (default: 30)")
    p_watch.add_argument("--duration", type=int, default=0, metavar="N",
                         help="Stop after N seconds (default: 0 = infinite)")
    p_watch.add_argument("--snapshot", action="store_true",
                         help="Auto-download and open the event JPEG when a new event arrives")
    p_watch.add_argument("--push", action="store_true",
                         help="Use FCM push notifications instead of polling (~2s latency, requires firebase-messaging)")
    p_watch.add_argument("--signal", metavar="URL",
                         help="Send alerts to Signal via signal-cli-rest-api (e.g. http://localhost:8080)")
    p_watch.add_argument("--signal-recipients", metavar="NUMS",
                         help="Comma-separated Signal recipients (phone numbers, e.g. +491234567890)")
    p_watch.add_argument("--signal-sender", metavar="NUM",
                         help="Signal sender number (your registered signal-cli number)")
    p_watch.add_argument("--push-mode", choices=["auto", "android", "ios", "polling"], default="auto",
                         help="Push notification mode: auto (try ios->android->polling), android, ios, polling")

    # ── intercom ────────────────────────────────────────────────────────────────
    p_intercom = subparsers.add_parser(
        "intercom",
        help="Open two-way audio (intercom) to a camera",
        description=(
            "🎤  intercom — Open a two-way audio session to a camera\n"
            "\n"
            "  Opens a live audio connection to the camera via the cloud proxy.\n"
            "  Plays camera audio through local speakers using ffplay.\n"
            "\n"
            "  Requires: ffmpeg (brew install ffmpeg)"
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py intercom Kamera\n"
            "    python3 bosch_camera.py intercom Garten --duration 120\n"
            "    python3 bosch_camera.py intercom Kamera --speaker-level 80"
        ),
    )
    p_intercom.add_argument("cam", nargs="?", help="Camera name")
    p_intercom.add_argument("--duration", type=int, default=60, help="Session duration in seconds (default 60)")
    p_intercom.add_argument("--speaker-level", type=int, default=50, help="Speaker volume 0-100 (default 50)")

    # ── motion ─────────────────────────────────────────────────────────────────
    p_motion = subparsers.add_parser(
        "motion",
        help="Get/set motion detection settings",
        description=(
            "🏃  motion — Get or set motion detection settings\n"
            "\n"
            "  Reads or writes the motion detection configuration.\n"
            "  API: GET/PUT /v11/video_inputs/{id}/motion\n"
            "\n"
            "  Sensitivity values: OFF | LOW | MEDIUM_LOW | MEDIUM_HIGH | HIGH | SUPER_HIGH"
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py motion Garten\n"
            "    python3 bosch_camera.py motion Garten --enable\n"
            "    python3 bosch_camera.py motion Garten --disable\n"
            "    python3 bosch_camera.py motion Garten --enable --sensitivity SUPER_HIGH\n"
            "    python3 bosch_camera.py motion Garten --sensitivity MEDIUM"
        ),
    )
    p_motion.add_argument("cam", nargs="?", help="Camera name (optional, all cameras if omitted)")
    p_motion.add_argument("--enable",  action="store_true", help="Enable motion detection")
    p_motion.add_argument("--disable", action="store_true", help="Disable motion detection")
    p_motion.add_argument("--sensitivity",
                          choices=["OFF", "LOW", "MEDIUM_LOW", "MEDIUM_HIGH", "HIGH", "SUPER_HIGH"],
                          metavar="S",
                          help="Sensitivity: OFF | LOW | MEDIUM | HIGH | SUPER_HIGH")

    # ── audio-alarm ────────────────────────────────────────────────────────────
    p_audio = subparsers.add_parser(
        "audio-alarm",
        help="Get/set audio alarm detection settings",
        description=(
            "🔊  audio-alarm — Get or set audio alarm detection settings\n"
            "\n"
            "  Reads or writes the audio alarm configuration.\n"
            "  API: GET/PUT /v11/video_inputs/{id}/audioAlarm\n"
            "\n"
            "  Threshold is 0-100 (higher = less sensitive)."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py audio-alarm Garten\n"
            "    python3 bosch_camera.py audio-alarm Garten --enable\n"
            "    python3 bosch_camera.py audio-alarm Garten --disable\n"
            "    python3 bosch_camera.py audio-alarm Garten --enable --threshold 60"
        ),
    )
    p_audio.add_argument("cam", nargs="?", help="Camera name (optional, all cameras if omitted)")
    p_audio.add_argument("--enable",    action="store_true", help="Enable audio alarm")
    p_audio.add_argument("--disable",   action="store_true", help="Disable audio alarm")
    p_audio.add_argument("--threshold", type=int, metavar="N",
                         help="Detection threshold 0-100 (higher = less sensitive)")

    # ── recording ──────────────────────────────────────────────────────────────
    p_rec = subparsers.add_parser(
        "recording",
        help="Get/set cloud recording options (sound on/off)",
        description=(
            "🎬  recording — Get or set cloud recording options\n"
            "\n"
            "  Reads or writes the recording configuration.\n"
            "  API: GET/PUT /v11/video_inputs/{id}/recording_options\n"
            "\n"
            "  Controls whether audio is included in cloud-stored recordings."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py recording Garten\n"
            "    python3 bosch_camera.py recording Garten --sound-on\n"
            "    python3 bosch_camera.py recording Garten --sound-off"
        ),
    )
    p_rec.add_argument("cam", nargs="?", help="Camera name (optional, all cameras if omitted)")
    p_rec.add_argument("--sound-on",  action="store_true", dest="sound_on",
                       help="Enable sound recording")
    p_rec.add_argument("--sound-off", action="store_true", dest="sound_off",
                       help="Disable sound recording")

    # ── autofollow ─────────────────────────────────────────────────────────────
    p_af = subparsers.add_parser(
        "autofollow",
        help="Get or set auto-follow (360 camera auto-tracks motion)",
        description=(
            "Auto-follow makes the indoor 360 camera automatically pan to track\n"
            "detected motion. Only available for cameras with panLimit > 0."
        ),
    )
    p_af.add_argument("cam", nargs="?", help="Camera name (optional)")
    p_af.add_argument("action", nargs="?", choices=["on", "off"],
                      help="on = enable auto-follow, off = disable")

    # ── siren ─────────────────────────────────────────────────────────────────
    p_siren = subparsers.add_parser(
        "siren",
        help="Trigger acoustic alarm (siren) on a camera",
        description=(
            "🔔  siren — Trigger the acoustic alarm on a camera\n"
            "\n"
            "  Only supported on CAMERA_360 (indoor). Outdoor cameras return HTTP 442."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    p_siren.add_argument("cam", nargs="?", help="Camera name")

    # ── unread ────────────────────────────────────────────────────────────────
    p_unread = subparsers.add_parser(
        "unread",
        help="Show unread event count per camera",
        description=(
            "📬  unread — Show unread event count per camera\n"
            "\n"
            "  Queries each camera for the number of unread events."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    p_unread.add_argument("cam", nargs="?", help="Camera name (optional, all cameras if omitted)")

    # ── privacy-sound ─────────────────────────────────────────────────────
    p_psound = subparsers.add_parser(
        "privacy-sound",
        help="Show or toggle privacy sound (audible indicator when privacy mode changes)",
        description=(
            "🔊  privacy-sound — Show or toggle privacy sound override\n"
            "\n"
            "  When enabled, the camera plays an audible indicator whenever\n"
            "  privacy mode is toggled on or off.\n"
            "  API: GET/PUT /v11/video_inputs/{id}/privacy_sound_override\n"
            "       Body: {\"result\": true/false}"
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py privacy-sound\n"
            "    python3 bosch_camera.py privacy-sound Garten\n"
            "    python3 bosch_camera.py privacy-sound on\n"
            "    python3 bosch_camera.py privacy-sound Garten on\n"
            "    python3 bosch_camera.py privacy-sound Garten off"
        ),
    )
    p_psound.add_argument(
        "cam",
        nargs="?",
        metavar="<camera>",
        help="Camera name or partial match (omit = all cameras)",
    )
    p_psound.add_argument(
        "action",
        nargs="?",
        metavar="on|off",
        choices=["on", "off"],
        help="Enable or disable privacy sound",
    )

    # ── rules ─────────────────────────────────────────────────────────────
    p_rules = subparsers.add_parser(
        "rules",
        help="Manage camera automation rules (time-based schedules)",
        description=(
            "📋  rules — Manage camera automation rules\n"
            "\n"
            "  Time-based schedules stored on the camera.\n"
            "  API: GET/POST/PUT/DELETE /v11/video_inputs/{id}/rules\n"
            "\n"
            "  Subcommands:\n"
            "    (none)  → list all rules for a camera\n"
            "    add     → create a new rule with name, time, days\n"
            "    edit    → update an existing rule (activate/deactivate)\n"
            "    delete  → remove a rule by ID"
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py rules Garten\n"
            "    python3 bosch_camera.py rules Garten add --name 'Night Mode' --start 22:00 --end 06:00 --days 0,1,2,3,4,5,6\n"
            "    python3 bosch_camera.py rules Garten edit --id UUID --active\n"
            "    python3 bosch_camera.py rules Garten edit --id UUID --inactive\n"
            "    python3 bosch_camera.py rules Garten delete --id UUID"
        ),
    )
    p_rules.add_argument(
        "cam",
        nargs="?",
        metavar="<camera>",
        help="Camera name or partial match (omit = all cameras)",
    )
    p_rules.add_argument(
        "sub",
        nargs="?",
        metavar="add|edit|delete",
        help="Subcommand: add, edit, or delete a rule",
    )
    p_rules.add_argument("--name", dest="rule_name", metavar="NAME",
                         help="Rule name (for add)")
    p_rules.add_argument("--start", default="00:00", metavar="HH:MM",
                         help="Start time (for add, default 00:00)")
    p_rules.add_argument("--end", default="23:59", metavar="HH:MM",
                         help="End time (for add, default 23:59)")
    p_rules.add_argument("--days", default="0,1,2,3,4,5,6", metavar="0,1,2,...",
                         help="Weekdays 0=Mon..6=Sun comma-separated (for add, default all)")
    p_rules.add_argument("--id", dest="rule_id", metavar="RULE_ID",
                         help="Rule ID (for edit/delete)")
    p_rules.add_argument("--active", action="store_true",
                         help="Activate the rule (for edit)")
    p_rules.add_argument("--inactive", action="store_true",
                         help="Deactivate the rule (for edit)")

    # ── friends ───────────────────────────────────────────────────────────
    p_friends = subparsers.add_parser(
        "friends",
        help="Manage camera sharing with friends",
        description=(
            "👥  friends — Manage camera sharing with friends\n"
            "\n"
            "  Invite friends, share cameras, manage invitations.\n"
            "  API: GET/POST/PUT/DELETE /v11/friends/*\n"
            "\n"
            "  Subcommands:\n"
            "    (none)  → list all friends\n"
            "    invite  → send invitation to an email address\n"
            "    share   → share a camera with a friend\n"
            "    unshare → remove all camera shares from a friend\n"
            "    resend  → re-send the invitation email\n"
            "    remove  → remove a friend entirely"
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py friends\n"
            "    python3 bosch_camera.py friends invite user@example.com\n"
            "    python3 bosch_camera.py friends share FRIEND_ID Garten\n"
            "    python3 bosch_camera.py friends share FRIEND_ID Garten --days 7\n"
            "    python3 bosch_camera.py friends unshare FRIEND_ID\n"
            "    python3 bosch_camera.py friends resend FRIEND_ID\n"
            "    python3 bosch_camera.py friends remove FRIEND_ID"
        ),
    )
    p_friends.add_argument(
        "sub",
        nargs="?",
        metavar="invite|share|unshare|resend|remove",
        help="Subcommand",
    )
    p_friends.add_argument(
        "sub_arg",
        nargs="?",
        metavar="EMAIL|FRIEND_ID",
        help="Email (for invite) or Friend ID (for other subcommands)",
    )
    p_friends.add_argument(
        "share_cam",
        nargs="?",
        metavar="<camera>",
        help="Camera name (for share subcommand)",
    )
    p_friends.add_argument("--days", type=int, metavar="N",
                           help="Share duration in days (for share; omit = permanent)")

    # ── accept-invite ─────────────────────────────────────────────────────
    p_accept = subparsers.add_parser(
        "accept-invite",
        help="Accept an incoming friend/camera sharing invitation",
        description=(
            "📨  accept-invite — Accept a friend invitation\n"
            "\n"
            "  Accepts an incoming camera sharing invitation using the\n"
            "  invitation token received from a friend.\n"
            "\n"
            "  API: POST /v11/friends/accept"
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py accept-invite ABC123TOKEN"
        ),
    )
    p_accept.add_argument(
        "token",
        metavar="TOKEN",
        help="Invitation token from the friend invitation",
    )

    # ── shared ────────────────────────────────────────────────────────────
    p_shared = subparsers.add_parser(
        "shared",
        help="Show which friends have access to a camera",
        description=(
            "🔗  shared — Show friends with access to a camera\n"
            "\n"
            "  Lists all friends who have been granted access to\n"
            "  a specific camera via camera sharing.\n"
            "\n"
            "  API: GET /v11/video_inputs/{id}/shared_with_friends"
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py shared\n"
            "    python3 bosch_camera.py shared Garten"
        ),
    )
    p_shared.add_argument("cam", nargs="?", metavar="<camera>",
                          help="Camera name (optional, default: all cameras)")

    # ── rename ────────────────────────────────────────────────────────────
    p_rename = subparsers.add_parser(
        "rename",
        help="Rename a camera",
        description=(
            "✏️   rename — Rename a camera via the Bosch cloud API\n"
            "\n"
            "  Changes the camera title stored in the Bosch cloud.\n"
            "  Also updates the local bosch_config.json.\n"
            "  API: PUT /v11/video_inputs"
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py rename Garten \"Garden Camera\"\n"
            "    python3 bosch_camera.py rename Kamera \"Indoor Cam\""
        ),
    )
    p_rename.add_argument(
        "cam",
        metavar="<camera>",
        help="Current camera name or partial match",
    )
    p_rename.add_argument(
        "new_name",
        metavar="\"New Name\"",
        help="New camera name (use quotes if it contains spaces)",
    )

    # ── profile ───────────────────────────────────────────────────────────
    p_profile = subparsers.add_parser(
        "profile",
        help="Show or edit user profile (name, email, marketing consent)",
        description=(
            "👤  profile — Show or edit user profile\n"
            "\n"
            "  Displays account info from the Bosch cloud:\n"
            "  name, email, last login, marketing consent, IoT integration.\n"
            "\n"
            "  API: GET /v11/registration/check, PUT /v11/registration"
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py profile\n"
            "    python3 bosch_camera.py profile edit --display-name 'John'\n"
            "    python3 bosch_camera.py profile edit --marketing off\n"
            "    python3 bosch_camera.py profile edit --display-name 'John' --marketing on"
        ),
    )
    p_profile.add_argument(
        "sub",
        nargs="?",
        metavar="edit",
        help="Subcommand: 'edit' to update profile",
    )
    p_profile.add_argument("--display-name", dest="display_name", metavar="NAME",
                           help="New display name")
    p_profile.add_argument("--marketing", metavar="on|off",
                           help="Marketing consent: on or off")

    # ── account ───────────────────────────────────────────────────────────
    subparsers.add_parser(
        "account",
        help="Show account info: feature flags, contracts, subscriptions",
        description=(
            "📊  account — Show account information\n"
            "\n"
            "  Displays feature flags, terms & conditions versions,\n"
            "  and active purchases/subscriptions.\n"
            "\n"
            "  API: GET /v11/feature_flags, GET /v11/contracts, GET /v11/purchases"
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="  Example:\n    python3 bosch_camera.py account",
    )

    # ── timestamp ──────────────────────────────────────────────────────────
    p_ts = subparsers.add_parser(
        "timestamp",
        help="Get or set time/date overlay on camera video",
        description=(
            "🕐  timestamp — Control the time/date overlay on camera video\n"
            "\n"
            "  API: GET/PUT /v11/video_inputs/{id}/timestamp\n"
            "       Body: {\"result\": true/false}"
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py timestamp\n"
            "    python3 bosch_camera.py timestamp kamera on\n"
            "    python3 bosch_camera.py timestamp garten off"
        ),
    )
    p_ts.add_argument("cam", nargs="?", metavar="<camera>",
                       help="Camera name (optional, default: all)")
    p_ts.add_argument("action", nargs="?", metavar="on|off",
                       help="on = show overlay, off = hide overlay")

    # ── notification-types ─────────────────────────────────────────────────
    p_nt = subparsers.add_parser(
        "notification-types",
        help="Show or toggle per-type notification settings",
        description=(
            "🔔  notification-types — Per-type notification toggles\n"
            "\n"
            "  Types: movement, person, audio, trouble, cameraAlarm\n"
            "  API: GET/PUT /v11/video_inputs/{id}/notifications"
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=(
            "  Examples:\n"
            "    python3 bosch_camera.py notification-types\n"
            "    python3 bosch_camera.py notification-types kamera --set movement=on person=off"
        ),
    )
    p_nt.add_argument("cam", nargs="?", metavar="<camera>",
                       help="Camera name (optional, default: all)")
    p_nt.add_argument("--set", nargs="+", metavar="key=on|off",
                       help="Set notification types (e.g. movement=on person=off)")

    # ── parse ──────────────────────────────────────────────────────────────────
    args = parser.parse_args()

    # Note: cmd_* functions read optional args exclusively via
    # getattr(args, "name", fallback) with per-call fallbacks. We deliberately do
    # NOT pre-populate missing attributes here — the previous `_defaults` dict
    # has been removed so argparse's own Namespace is the single source of truth.

    # Load (or create) config
    cfg = load_config()

    if not args.command:
        # If no cameras yet, do initial discovery
        if not cfg.get("cameras"):
            print("\n  🆕  First run — let's set up your cameras.\n")
            token   = get_token(cfg)
            session = make_session(token)
            cameras = discover_cameras(cfg, session)
            if cameras:
                print(f"\n  Found {len(cameras)} camera(s): {', '.join(cameras.keys())}")
        while True:
            cmd_menu(cfg)
        return

    cmd = args.command.lower()
    # liveshot / livesnap / live-snapshot are aliases for snapshot --live
    if cmd in ("liveshot", "livesnap", "live-snapshot"):
        args.live = True
        cmd = "snapshot"
    # stream is an alias for live
    if cmd == "stream":
        cmd = "live"

    dispatch = {
        "status":        cmd_status,
        "info":          cmd_info,
        "snapshot":      cmd_snapshot,
        "live":          cmd_live,
        # "download" and "events" removed (Bosch request)
        "privacy":       cmd_privacy,
        "light":         cmd_light,
        "pan":           cmd_pan,
        "notifications": cmd_notifications,
        "watch":         cmd_watch,
        "motion":        cmd_motion,
        "audio-alarm":   cmd_audio_alarm,
        "recording":     cmd_recording,
        "autofollow":    cmd_autofollow,
        "siren":         cmd_siren,
        "unread":        cmd_unread,
        "privacy-sound": cmd_privacy_sound,
        "rules":         cmd_rules,
        "friends":       cmd_friends,
        "accept-invite": cmd_accept_invite,
        "shared":        cmd_shared_with_friends,
        "zones":         cmd_zones,
        "privacy-masks": cmd_privacy_masks,
        "lighting-schedule": cmd_lighting_schedule,
        "rename":        cmd_rename,
        "profile":       cmd_profile,
        "account":       cmd_account,
        "intercom":      cmd_intercom,
        "rcp":                cmd_rcp,
        "token":              cmd_token,
        "config":             cmd_config,
        "rescan":             cmd_rescan,
        "timestamp":          cmd_timestamp,
        "notification-types": cmd_notification_types,
        "test-local":         cmd_test_local,
    }
    if cmd not in dispatch:
        print(f"❌  Unknown command '{cmd}'. Run without arguments for the menu.")
        sys.exit(1)
    dispatch[cmd](cfg, args)


if __name__ == "__main__":
    main()