hap-cli 0.5.0__py3-none-any.whl

hap_cli/core/app.py

@@ -0,0 +1,307 @@
+"""Application management module for MingDAO HAP."""
+
+from typing import Any, Optional
+
+from hap_cli.core.session import Session
+
+
+def get_app_info(session: Session, app_id: str) -> dict[str, Any]:
+    """Get application information (basic, no sections).
+
+    Args:
+        session: Active session
+        app_id: Application ID
+
+    Returns:
+        Application info dict
+    """
+    return session.api_call("HomeApp", "GetApp", {"appId": app_id})
+
+
+def get_app_detail(session: Session, app_id: str) -> dict[str, Any]:
+    """Get detailed application information including sections and worksheets.
+
+    Args:
+        session: Active session
+        app_id: Application ID
+
+    Returns:
+        Application detail dict with sections and worksheet lists
+    """
+    return session.api_call(
+        "HomeApp", "GetApp",
+        {"appId": app_id, "getSection": True, "getManager": True, "getLang": True},
+    )
+
+
+def get_app_worksheets(
+    session: Session, app_id: str, app_section_id: str = ""
+) -> list[dict[str, Any]]:
+    """List worksheets in an application.
+
+    Calls GetApp with getSection=true, then flattens all workSheetInfo arrays
+    from all sections (optionally filtered by appSectionId).
+
+    Args:
+        session: Active session
+        app_id: Application ID
+        app_section_id: Optional section ID to filter to a single section
+
+    Returns:
+        List of worksheet info dicts
+    """
+    result = session.api_call(
+        "HomeApp", "GetApp",
+        {"appId": app_id, "getSection": True, "getManager": True, "getLang": True},
+    )
+    sections = result.get("sections", [])
+    worksheets: list[dict[str, Any]] = []
+    for sec in sections:
+        if app_section_id and sec.get("appSectionId") != app_section_id:
+            continue
+        worksheets.extend(sec.get("workSheetInfo", []))
+    return worksheets
+
+
+def get_managed_apps(session: Session, project_id: str) -> list[dict[str, Any]]:
+    """List applications where the user is a manager.
+
+    Args:
+        session: Active session
+        project_id: Project/organization ID
+
+    Returns:
+        List of application info dicts with appId, name, worksheetCount
+    """
+    result = session.api_call(
+        "AppManagement", "GetAppForManager",
+        {"projectId": project_id, "type": 0},
+    )
+    apps = result if isinstance(result, list) else []
+    return [
+        {
+            "appId": app.get("appId", ""),
+            "name": app.get("appName", ""),
+            "worksheetCount": len(app.get("workSheetInfo", [])),
+        }
+        for app in apps
+    ]
+
+
+def get_all_home_apps(session: Session, project_id: str) -> list[dict[str, Any]]:
+    """List applications for a specific project.
+
+    Calls GetAllHomeApp and filters validProject entries by projectId.
+
+    Args:
+        session: Active session
+        project_id: Project/organization ID to filter by
+
+    Returns:
+        List of application info dicts with appId, name, orgName, projectId
+    """
+    result = session.api_call("HomeApp", "GetAllHomeApp", {"containsLinks": False})
+    apps: list[dict[str, Any]] = []
+    valid_projects = result if isinstance(result, list) else result.get("validProject", [])
+    for project in valid_projects:
+        if project.get("projectId") != project_id:
+            continue
+        org_name = project.get("projectName", "")
+        for app in project.get("projectApps", []):
+            apps.append({
+                "appId": app.get("id", ""),
+                "name": app.get("name", ""),
+                "orgName": org_name,
+                "projectId": project_id,
+            })
+    return apps
+
+
+# ── App Lifecycle ────────────────────────────────────────────────────────
+
+
+def create_app(
+    session: Session,
+    project_id: str,
+    name: str,
+    icon: str = "",
+    icon_color: str = "",
+    nav_color: str = "",
+) -> dict[str, Any]:
+    """Create a new application."""
+    data: dict[str, Any] = {"projectId": project_id, "name": name}
+    if icon:
+        data["icon"] = icon
+    if icon_color:
+        data["iconColor"] = icon_color
+    if nav_color:
+        data["navColor"] = nav_color
+    return session.api_call("HomeApp", "CreateApp", data)
+
+
+def update_app(
+    session: Session,
+    app_id: str,
+    name: str = "",
+    description: str = "",
+    icon_color: str = "",
+    nav_color: str = "",
+    project_id: str = "",
+) -> dict[str, Any]:
+    """Update application information."""
+    data: dict[str, Any] = {"appId": app_id}
+    if name:
+        data["name"] = name
+    if description:
+        data["description"] = description
+    if icon_color:
+        data["iconColor"] = icon_color
+    if nav_color:
+        data["navColor"] = nav_color
+    if project_id:
+        data["projectId"] = project_id
+    return session.api_call("HomeApp", "EditAppInfo", data)
+
+
+def delete_app(session: Session, app_id: str, project_id: str) -> dict[str, Any]:
+    """Delete an application."""
+    return session.api_call(
+        "HomeApp", "DeleteApp",
+        {"appId": app_id, "projectId": project_id},
+    )
+
+
+# ── Section (app group) management ──────────────────────────────────────
+
+
+def add_section(
+    session: Session, app_id: str, name: str = "",
+) -> dict[str, Any]:
+    """Add a section/group to an application."""
+    data: dict[str, Any] = {"appId": app_id}
+    if name:
+        data["name"] = name
+    return session.api_call("HomeApp", "AddAppSection", data)
+
+
+def edit_section(
+    session: Session, app_id: str, section_id: str, name: str,
+) -> dict[str, Any]:
+    """Edit a section name."""
+    return session.api_call(
+        "HomeApp", "UpdateAppSection",
+        {"appId": app_id, "sectionId": section_id, "name": name},
+    )
+
+
+def delete_section(
+    session: Session, app_id: str, section_id: str,
+) -> dict[str, Any]:
+    """Delete a section from an application."""
+    return session.api_call(
+        "HomeApp", "DeleteAppSection",
+        {"appId": app_id, "sectionId": section_id},
+    )
+
+
+# ── Backup / Export ──────────────────────────────────────────────────────
+
+
+def backup_app(
+    session: Session, app_id: str, project_id: str, contain_data: bool = True,
+) -> dict[str, Any]:
+    """Backup an application."""
+    return session.api_call(
+        "AppManagement", "Backup",
+        {"appId": app_id, "projectId": project_id, "containData": contain_data},
+    )
+
+
+def restore_app(
+    session: Session,
+    app_id: str,
+    project_id: str,
+    backup_id: str,
+    file_url: str,
+    file_name: str,
+    contain_data: bool = True,
+    is_restore_new: bool = False,
+) -> dict[str, Any]:
+    """Restore an application from backup."""
+    return session.api_call(
+        "AppManagement", "Restore",
+        {
+            "appId": app_id,
+            "projectId": project_id,
+            "id": backup_id,
+            "fileUrl": file_url,
+            "fileName": file_name,
+            "containData": contain_data,
+            "isRestoreNew": is_restore_new,
+        },
+    )
+
+
+def export_apps(session: Session, app_ids: list[str]) -> dict[str, Any]:
+    """Batch export applications."""
+    return session.api_call("AppManagement", "BatchExportApp", {"appIds": app_ids})
+
+
+def get_exports(session: Session, app_id: str) -> dict[str, Any]:
+    """Get export list for an application."""
+    return session.api_call("AppManagement", "GetExportsByApp", {"appId": app_id})
+
+
+def get_backup_logs(
+    session: Session,
+    app_id: str,
+    project_id: str,
+    page_index: int = 1,
+    page_size: int = 20,
+) -> dict[str, Any]:
+    """Get backup/restore operation logs."""
+    return session.api_call(
+        "AppManagement", "PageGetBackupRestoreOperationLog",
+        {
+            "appId": app_id,
+            "projectId": project_id,
+            "pageIndex": page_index,
+            "pageSize": page_size,
+        },
+    )
+
+
+# ── Usage & Logs ─────────────────────────────────────────────────────────
+
+
+def get_usage_stats(
+    session: Session,
+    project_id: str,
+    app_id: str = "",
+    day_range: int = 7,
+) -> dict[str, Any]:
+    """Get application usage statistics."""
+    data: dict[str, Any] = {"projectId": project_id, "dayRange": day_range}
+    if app_id:
+        data["appId"] = app_id
+    return session.api_call(
+        "AppManagement", "AllUsageOverviewStatistics", data,
+    )
+
+
+def get_app_logs(
+    session: Session,
+    app_id: str,
+    page_index: int = 1,
+    page_size: int = 50,
+) -> dict[str, Any]:
+    """Get application operation logs."""
+    return session.api_call(
+        "AppManagement", "GetLogs",
+        {"appId": app_id, "pageIndex": page_index, "pageSize": page_size},
+    )
+
+
+def get_app_langs(session: Session, app_id: str) -> dict[str, Any]:
+    """Get application language list."""
+    return session.api_call("AppManagement", "GetAppLangs", {"appId": app_id})

hap_cli/core/auth.py

@@ -0,0 +1,219 @@
+"""Browser-based authentication flow for MingDAO HAP.
+
+Implements a local callback server pattern:
+1. Start local HTTP server on a free port
+2. Open browser to HAP login page with callback URL
+3. Capture token from redirect, save to config
+"""
+
+import base64
+import json
+import socket
+import threading
+import webbrowser
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from typing import Optional
+from urllib.parse import urlparse, parse_qs
+
+import requests
+
+from hap_cli.core.session import _main_api_base_for_url
+
+# Known server presets: name -> (api_base, webui_url)
+# api_base is kept for backward compatibility with resolve_server callers.
+SERVER_PRESETS = {
+    "mingdao": ("https://www.mingdao.com/api", "https://www.mingdao.com"),
+    "nocoly": ("https://www.nocoly.com/wwwapi", "https://www.nocoly.com"),
+}
+
+
+def resolve_server(server: str) -> tuple[str, str]:
+    """Resolve server name or URL to (api_host, webui_url).
+
+    Args:
+        server: Preset name ('mingdao', 'nocoly') or self-hosted URL.
+
+    Returns:
+        Tuple of (api_host, webui_url).
+    """
+    key = server.lower().strip()
+    if key in SERVER_PRESETS:
+        return SERVER_PRESETS[key]
+
+    # Self-hosted: URL is both webui base and API base
+    base = server.rstrip("/")
+    return (f"{base}/wwwapi", base)
+
+
+def get_available_port(start: int = 5100) -> int:
+    """Find an available TCP port starting from `start`."""
+    for port in range(start, start + 100):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            try:
+                s.bind(("127.0.0.1", port))
+                return port
+            except OSError:
+                continue
+    raise RuntimeError("No available port found in range 5100-5199")
+
+
+def build_auth_url(webui: str, port: int) -> str:
+    """Build the browser auth URL with base64-encoded callback info."""
+    callback_info = json.dumps({"url": f"http://localhost:{port}"})
+    encoded = base64.b64encode(callback_info.encode()).decode()
+    return f"{webui}/cliauth?p={encoded}"
+
+
+def _decrypt_response(encrypted_value: str, decrypt_key: str) -> dict:
+    """Decrypt AES-CBC encrypted API response (private deployments).
+
+    Requires pycryptodome: pip install pycryptodome
+    """
+    try:
+        from Crypto.Cipher import AES
+    except ImportError:
+        raise ImportError(
+            "pycryptodome is required for encrypted responses. "
+            "Install it with: pip install pycryptodome"
+        )
+
+    IV = b"MIGfMA0GCSqGSIb3"  # Fixed 16-byte IV
+    key_bytes = decrypt_key.encode("utf-8")
+    key_len = len(key_bytes)
+    required_len = 16 if key_len <= 16 else (24 if key_len <= 24 else 32)
+    padded_key = key_bytes[:required_len].ljust(required_len, b"\x00")
+    cipher = AES.new(padded_key, AES.MODE_CBC, IV)
+    ct = base64.b64decode(encrypted_value)
+    decrypted = cipher.decrypt(ct)
+    pad_len = decrypted[-1]
+    raw = decrypted[:-pad_len].decode("utf-8").replace("\t", "\\t")
+    return json.loads(raw)
+
+
+def get_user_info(host: str, token: str) -> dict:
+    """Verify token and get user info via GetGlobalMeta API.
+
+    Args:
+        host: Login URL or API base URL (e.g. 'https://www.mingdao.com' or
+              'https://www.mingdao.com/api'). Host type is auto-detected.
+        token: Auth token.
+
+    Returns:
+        Dict with keys: id, name, email, avatar, lang.
+
+    Raises:
+        requests.HTTPError: If API call fails.
+        ValueError: If response is invalid or token is rejected.
+    """
+    url = _main_api_base_for_url(host) + "/Global/GetGlobalMeta"
+    resp = requests.post(
+        url,
+        json={},
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"md_pss_id {token}",
+        },
+        timeout=15,
+    )
+    resp.raise_for_status()
+    raw = resp.json()
+
+    if raw.get("state") == 0:
+        raise ValueError(raw.get("exception", "Token verification failed"))
+
+    # Handle encrypted responses (private deployments)
+    if raw.get("encrypted") and raw.get("key"):
+        data = _decrypt_response(raw["data"], raw["key"])
+    else:
+        data = raw
+
+    account = data.get("data", {}).get("md.global", {}).get("Account", {})
+    if not account:
+        raise ValueError("Unable to extract account info from response")
+
+    return {
+        "id": account.get("accountId", ""),
+        "name": account.get("fullname", ""),
+        "email": account.get("email", ""),
+        "avatar": account.get("avatar", ""),
+        "lang": account.get("lang", ""),
+    }
+
+
+def login(server: str, timeout: int = 300) -> tuple[str, str, dict]:
+    """Run the full browser-based login flow.
+
+    Args:
+        server: Preset name ('mingdao', 'nocoly') or self-hosted URL.
+        timeout: Max seconds to wait for user to complete login.
+
+    Returns:
+        Tuple of (token, api_host, user_info).
+
+    Raises:
+        TimeoutError: If user does not complete login in time.
+    """
+    api_host, webui = resolve_server(server)
+    port = get_available_port()
+
+    received = threading.Event()
+    result: dict = {}
+    server_ref: dict = {}
+
+    class AuthCallbackHandler(BaseHTTPRequestHandler):
+        def do_OPTIONS(self):
+            self.send_response(204)
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+            self.send_header("Access-Control-Allow-Headers", "Content-Type")
+            self.end_headers()
+
+        def do_GET(self):
+            self.send_header("Access-Control-Allow-Origin", "*")
+            parsed = urlparse(self.path)
+            params = parse_qs(parsed.query)
+            encoded_token = params.get("t", [None])[0]
+
+            if not encoded_token:
+                self.send_response(400)
+                self.end_headers()
+                self.wfile.write(b"No token provided")
+                return
+
+            token = base64.b64decode(encoded_token).decode("utf-8")
+            result["token"] = token
+
+            # Redirect browser to success page
+            self.send_response(302)
+            self.send_header("Location", f"{webui}/cliauth/success")
+            self.end_headers()
+
+            # Shut down server after responding
+            threading.Timer(
+                0.1,
+                lambda: (server_ref["srv"].shutdown(), received.set()),
+            ).start()
+
+        def log_message(self, format, *args):
+            pass  # Suppress HTTP server logs
+
+    srv = HTTPServer(("127.0.0.1", port), AuthCallbackHandler)
+    server_ref["srv"] = srv
+
+    thread = threading.Thread(target=srv.serve_forever, daemon=True)
+    thread.start()
+
+    auth_url = build_auth_url(webui, port)
+    webbrowser.open(auth_url)
+
+    received.wait(timeout=timeout)
+
+    token = result.get("token")
+    if not token:
+        raise TimeoutError("Login timed out — no token received")
+
+    # Verify token and get user info
+    user_info = get_user_info(webui, token)
+    # Return the login URL (webui), not the API base, so callers store
+    # the canonical login URL in session config.
+    return token, webui, user_info

hap_cli/core/calendar_mod.py

@@ -0,0 +1,114 @@
+"""Calendar and schedule management for MingDAO HAP.
+
+Named calendar_mod.py to avoid conflict with Python stdlib calendar module.
+"""
+
+from typing import Any, Optional
+
+from hap_cli.core.session import Session
+
+
+def get_calendars(
+    session: Session,
+    start_date: str,
+    end_date: str,
+    project_id: str = "",
+) -> dict[str, Any]:
+    """Get calendar events list."""
+    data: dict[str, Any] = {"startDate": start_date, "endDate": end_date}
+    if project_id:
+        data["projectId"] = project_id
+    return session.api_call("Calendar", "GetCalendars", data)
+
+
+def get_calendar_detail(
+    session: Session,
+    calendar_id: str,
+) -> dict[str, Any]:
+    """Get calendar event detail."""
+    return session.api_call("Calendar", "GetCalendarDetail", {"calendarId": calendar_id})
+
+
+def insert_calendar(
+    session: Session,
+    name: str,
+    start_date: str,
+    end_date: str,
+    description: str = "",
+    is_private: bool = False,
+    cat_id: str = "",
+) -> dict[str, Any]:
+    """Create a new calendar event."""
+    data: dict[str, Any] = {
+        "name": name,
+        "startDate": start_date,
+        "endDate": end_date,
+        "isPrivate": is_private,
+    }
+    if description:
+        data["description"] = description
+    if cat_id:
+        data["catId"] = cat_id
+    return session.api_call("Calendar", "InsertCalendar", data)
+
+
+def edit_calendar(
+    session: Session,
+    calendar_id: str,
+    name: str = "",
+    start_date: str = "",
+    end_date: str = "",
+    description: str = "",
+) -> dict[str, Any]:
+    """Edit a calendar event."""
+    data: dict[str, Any] = {"calendarId": calendar_id}
+    if name:
+        data["name"] = name
+    if start_date:
+        data["startDate"] = start_date
+    if end_date:
+        data["endDate"] = end_date
+    if description:
+        data["description"] = description
+    return session.api_call("Calendar", "EditCalendar", data)
+
+
+def delete_calendar(
+    session: Session,
+    calendar_id: str,
+    recur_time: str = "",
+) -> dict[str, Any]:
+    """Delete a calendar event."""
+    data: dict[str, Any] = {"calendarId": calendar_id}
+    if recur_time:
+        data["recurTime"] = recur_time
+    return session.api_call("Calendar", "DeleteCalendar", data)
+
+
+def add_members(
+    session: Session,
+    calendar_id: str,
+    member_ids: list[str],
+) -> dict[str, Any]:
+    """Add members to a calendar event."""
+    return session.api_call(
+        "Calendar", "AddMembers",
+        {"calendarId": calendar_id, "memberIds": member_ids},
+    )
+
+
+def remove_member(
+    session: Session,
+    calendar_id: str,
+    account_id: str,
+) -> dict[str, Any]:
+    """Remove a member from a calendar event."""
+    return session.api_call(
+        "Calendar", "RemoveMember",
+        {"calendarId": calendar_id, "accountId": account_id},
+    )
+
+
+def get_categories(session: Session) -> dict[str, Any]:
+    """Get all calendar categories."""
+    return session.api_call("Calendar", "GetUserAllCalCategories", {})