ermes-cli 1.0.0__py3-none-any.whl

ermes_cli/config.py

@@ -0,0 +1,393 @@
+"""Config storage for ermes-cli.
+
+Two storage shapes coexist:
+
+  ~/.ermes/projects.yml  (new in v0.3, written by `ermes login`)
+      auth0_email: admin@ermes.local
+      active_project: 72
+      base_url: https://ermes.publinker.com
+      projects:
+        72:
+          name: martechdm
+          organization_id: 1
+          role: admin
+          api_key: sk_xxxxx
+          api_key_id: 42
+          api_key_name: cli-managed-<hostname>
+
+  ~/.ermes/config.yml   (legacy, written by `ermes config init`)
+      default_profile: martechdm
+      profiles:
+        martechdm:
+          api_key: sk_xxxxx
+          base_url: https://ermes.publinker.com
+
+`resolve_profile()` prefers projects.yml (see its docstring for the full
+1.0 order). Per-project keys are provisioned lazily on first use — login
+no longer mints a key on every project.
+
+Both files are written chmod 600.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+DEFAULT_BASE_URL = "https://ermes.publinker.com"
+
+
+_warned_profile: list[bool] = []
+
+
+class ConfigError(Exception):
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Paths
+# ---------------------------------------------------------------------------
+
+
+def _config_dir() -> Path:
+    return Path(os.environ.get("ERMES_CONFIG_DIR", Path.home() / ".ermes"))
+
+
+def _config_path() -> Path:
+    return _config_dir() / "config.yml"
+
+
+def _projects_path() -> Path:
+    return _config_dir() / "projects.yml"
+
+
+# ---------------------------------------------------------------------------
+# Legacy profile storage (config.yml)
+# ---------------------------------------------------------------------------
+
+
+def load_config() -> dict:
+    path = _config_path()
+    if not path.exists():
+        return {"profiles": {}}
+    with open(path) as f:
+        data = yaml.safe_load(f)
+    return data if data else {"profiles": {}}
+
+
+@contextlib.contextmanager
+def _open_private(path: Path):
+    """Write `path` atomically as a fresh 0600 file.
+
+    The bytes go to a sibling temp file opened O_EXCL|O_NOFOLLOW (a planted
+    symlink or stale temp is never followed), then `os.replace` swaps it in: a
+    reader sees the old file or the new one, never a truncated one, and a
+    pre-existing wide-mode file or symlink is replaced by a fresh 0600 inode.
+    """
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.unlink(missing_ok=True)
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), 0o600)
+    try:
+        if hasattr(os, "fchmod"):  # absent on Windows < 3.13; the 0o600 at open still applies
+            os.fchmod(fd, 0o600)
+        f = os.fdopen(fd, "w")
+    except OSError:
+        os.close(fd)
+        tmp.unlink(missing_ok=True)
+        raise
+    try:
+        with f:
+            yield f
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, path)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+def validate_api_key(raw: str, source: str = "API key") -> str:
+    """A key with whitespace or control chars would make httpx raise a header
+    error that repeats the whole key; reject it before it reaches the client."""
+    key = raw.strip()
+    if not key or any(ch.isspace() or not ch.isprintable() for ch in key):
+        raise ConfigError(
+            f"{source} contains whitespace or control characters; "
+            "use the bare sk_… value (watch for a trailing newline)."
+        )
+    return key
+
+
+def save_config(config: dict) -> None:
+    path = _config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with _open_private(path) as f:
+        yaml.dump(config, f, default_flow_style=False)
+
+
+def add_profile(name: str, api_key: str, base_url: str | None = None) -> None:
+    config = load_config()
+    if name in config.get("profiles", {}):
+        raise ConfigError(f"Profile '{name}' already exists")
+    config.setdefault("profiles", {})[name] = {
+        "api_key": api_key,
+        "base_url": base_url or DEFAULT_BASE_URL,
+    }
+    if not config.get("default_profile"):
+        config["default_profile"] = name
+    save_config(config)
+
+
+def remove_profile(name: str) -> None:
+    config = load_config()
+    if name not in config.get("profiles", {}):
+        raise ConfigError(f"Profile '{name}' not found")
+    del config["profiles"][name]
+    if config.get("default_profile") == name:
+        config["default_profile"] = None
+    save_config(config)
+
+
+def get_profile(name: str) -> dict:
+    config = load_config()
+    if name not in config.get("profiles", {}):
+        raise ConfigError(f"Profile '{name}' not found")
+    return config["profiles"][name]
+
+
+def set_default_profile(name: str) -> None:
+    config = load_config()
+    if name not in config.get("profiles", {}):
+        raise ConfigError(f"Profile '{name}' not found")
+    config["default_profile"] = name
+    save_config(config)
+
+
+def mask_key(key: str) -> str:
+    if len(key) <= 8:
+        return key[:3] + "***"
+    return key[:3] + "***" + key[-3:]
+
+
+def list_profiles() -> list[dict]:
+    config = load_config()
+    default = config.get("default_profile")
+    result = []
+    for name, profile in config.get("profiles", {}).items():
+        result.append({
+            "name": name,
+            "api_key": mask_key(profile["api_key"]),
+            "base_url": profile.get("base_url", DEFAULT_BASE_URL),
+            "is_default": name == default,
+        })
+    return result
+
+
+# ---------------------------------------------------------------------------
+# New project storage (projects.yml) — populated by `ermes login`
+# ---------------------------------------------------------------------------
+
+
+def load_projects_file() -> dict[str, Any]:
+    path = _projects_path()
+    if not path.exists():
+        return {}
+    with open(path) as f:
+        data = yaml.safe_load(f)
+    return data if isinstance(data, dict) else {}
+
+
+def save_projects_file(data: dict[str, Any]) -> None:
+    path = _projects_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with _open_private(path) as f:
+        yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+
+
+def clear_projects_file() -> None:
+    path = _projects_path()
+    if path.exists():
+        path.unlink()
+
+
+def get_projects() -> dict[int, dict[str, Any]]:
+    data = load_projects_file()
+    raw = data.get("projects") or {}
+    # YAML keys may come back as strings; normalize to int.
+    return {int(k): v for k, v in raw.items()}
+
+
+def get_active_project_id() -> int | None:
+    data = load_projects_file()
+    aid = data.get("active_project")
+    return int(aid) if aid is not None else None
+
+
+def set_active_project_id(project_id: int) -> None:
+    data = load_projects_file()
+    projects = data.get("projects") or {}
+    if str(project_id) not in projects and project_id not in projects:
+        raise ConfigError(
+            f"Project {project_id} not in projects.yml — run `ermes login` to refresh"
+        )
+    data["active_project"] = int(project_id)
+    save_projects_file(data)
+
+
+def get_active_project() -> dict[str, Any] | None:
+    aid = get_active_project_id()
+    if aid is None:
+        return None
+    return get_projects().get(aid)
+
+
+def get_effective_project(
+    profile_name: str | None = None,
+) -> tuple[int | None, dict[str, Any] | None, str]:
+    """The project commands will ACTUALLY use, and where that came from.
+
+    MUST mirror every tier of `resolve_profile()` — an earlier cut only handled
+    ERMES_PROJECT and active_project, so `whoami` printed one project while the
+    data commands used a legacy config.yml key. Tiers that resolve through
+    config.yml or ERMES_API_KEY carry no project identity and return
+    `(None, None, source)`. Returns `(id, project, source)`.
+    """
+    if profile_name:
+        return None, None, f"--profile {profile_name!r} (legacy config.yml, no project identity)"
+
+    if os.environ.get("ERMES_API_KEY"):
+        return None, None, "ERMES_API_KEY (no project identity)"
+
+    env_project = os.environ.get("ERMES_PROJECT")
+    if env_project:
+        projects = get_projects()
+        if env_project.isdigit():
+            pid = int(env_project)
+            if pid in projects:
+                return pid, projects[pid], "ERMES_PROJECT"
+        else:
+            for pid, proj in projects.items():
+                if proj.get("name", "").lower() == env_project.lower():
+                    return pid, proj, "ERMES_PROJECT"
+        # Unresolvable override: say so rather than silently falling back to the active project,
+        # which would display a project the very next command is NOT going to use.
+        return None, None, f"ERMES_PROJECT={env_project!r} (NOT FOUND)"
+
+    active_id, active = get_active_project_id(), get_active_project()
+    if active is not None:
+        return active_id, active, "projects.yml"
+
+    env_profile = os.environ.get("ERMES_PROFILE")
+    if env_profile:
+        return (
+            None,
+            None,
+            f"ERMES_PROFILE={env_profile!r} (legacy config.yml, no project identity)",
+        )
+    return active_id, active, "projects.yml"
+
+
+def get_base_url() -> str:
+    data = load_projects_file()
+    return data.get("base_url") or DEFAULT_BASE_URL
+
+
+def get_auth0_email() -> str | None:
+    data = load_projects_file()
+    email = data.get("auth0_email")
+    return str(email) if email else None
+
+
+# ---------------------------------------------------------------------------
+# Profile resolution — what the CLI / MCP actually consume at runtime
+# ---------------------------------------------------------------------------
+
+
+def resolve_profile(profile_name: str | None = None) -> dict:
+    """Resolve to a `{base_url, api_key}` dict.
+
+    Resolution order (1.0):
+      1. Explicit `profile_name` arg (always wins; reads legacy config.yml)
+      2. `ERMES_API_KEY` env (+ optional `ERMES_BASE_URL`) — CI / scripts, no login
+      3. `ERMES_PROJECT` env (matches projects.yml by name or id)
+      4. projects.yml `active_project` (the post-`ermes login` happy path)
+      5. `ERMES_PROFILE` env (legacy, deprecated — ranked below the project tiers)
+      6. legacy config.yml `default_profile`
+
+    A project without a cached key (login no longer mints keys for every project)
+    is provisioned on first use via `POST /api/admin/projects/:id/cli-key`.
+    Raises `ConfigError` with an actionable message if nothing resolves.
+    """
+    if profile_name:
+        return get_profile(profile_name)
+
+    env_key = os.environ.get("ERMES_API_KEY")
+    if env_key:
+        return {
+            "base_url": os.environ.get("ERMES_BASE_URL") or get_base_url(),
+            "api_key": validate_api_key(env_key, "ERMES_API_KEY"),
+        }
+
+    env_profile = os.environ.get("ERMES_PROFILE")
+    if env_profile and not _warned_profile:
+        _warned_profile.append(True)
+        print(
+            "ermes: ERMES_PROFILE is deprecated and now ranks below ERMES_PROJECT and the "
+            "active project; use ERMES_PROJECT=<name-or-id> or ERMES_API_KEY.",
+            file=sys.stderr,
+        )
+
+    env_project = os.environ.get("ERMES_PROJECT")
+    if env_project:
+        return _resolve_from_projects(env_project)
+
+    active_id = get_active_project_id()
+    if active_id is not None and active_id in get_projects():
+        return {"base_url": get_base_url(), "api_key": _project_key(active_id)}
+
+    if env_profile:
+        return get_profile(env_profile)
+
+    config = load_config()
+    default = config.get("default_profile")
+    if default:
+        return get_profile(default)
+
+    raise ConfigError(
+        "No active profile. Run `ermes login` to authenticate via Auth0 and "
+        "auto-discover your projects, or set ERMES_API_KEY for a scripted session."
+    )
+
+
+def _project_key(project_id: int) -> str:
+    """Cached per-admin key for the project, provisioning it on first use."""
+    proj = get_projects().get(project_id) or {}
+    if proj.get("api_key"):
+        return str(proj["api_key"])
+    from ermes_cli.commands.auth_cmds import ensure_project_key  # lazy: avoids an import cycle
+
+    return ensure_project_key(project_id)
+
+
+def _resolve_from_projects(name_or_id: str) -> dict:
+    """Look up a project in projects.yml by name OR numeric id."""
+    projects = get_projects()
+    if name_or_id.isdigit():
+        pid = int(name_or_id)
+        if pid in projects:
+            return {"base_url": get_base_url(), "api_key": _project_key(pid)}
+        raise ConfigError(
+            f"ERMES_PROJECT={name_or_id}: project id not found in projects.yml"
+        )
+    for pid, proj in projects.items():
+        if proj.get("name", "").lower() == name_or_id.lower():
+            return {"base_url": get_base_url(), "api_key": _project_key(pid)}
+    raise ConfigError(
+        f"ERMES_PROJECT={name_or_id!r} not found in projects.yml — "
+        "run `ermes projects refresh`"
+    )

ermes_cli/errors.py

@@ -0,0 +1,34 @@
+"""Shared exception hierarchy for ermes-cli.
+
+Lives in its own module so `client.py` and `write_mode.py` can both import
+from it without a circular dependency.
+
+Hierarchy:
+    ErmesAPIError                         # base — any failure interacting with the API
+        WriteBlockedError                 # client-side guard fired before the request
+"""
+
+from __future__ import annotations
+
+
+class ErmesAPIError(Exception):
+    """Anything that prevents an Ermes API call from succeeding cleanly.
+
+    `status_code` is the HTTP status when the failure came from the server.
+    For pre-flight failures (no network call made) it's None.
+    """
+
+    def __init__(self, message: str, status_code: int | None = None):
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class WriteBlockedError(ErmesAPIError):
+    """Raised by the write-mode guard before a mutating call hits the network.
+
+    Inherits from ErmesAPIError so the existing `try/except ErmesAPIError`
+    blocks in every command file catch it without modification.
+    """
+
+    def __init__(self, message: str):
+        super().__init__(message, status_code=None)

ermes_cli/export_utils.py

@@ -0,0 +1,263 @@
+# cli/ermes_cli/export_utils.py
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+try:
+    from zoneinfo import ZoneInfo
+except ImportError:
+    ZoneInfo = None  # type: ignore
+
+# Pre-compiled patterns
+_LINK_PATTERN = re.compile(r'href=[\'"]?([^\'" >]+)', re.IGNORECASE)
+_HTML_TAG_PATTERN = re.compile(r'<[^>]+>')
+_WHITESPACE_PATTERN = re.compile(r'\s+')
+_EMOJI_PATTERN = re.compile(
+    "[" +
+    "\U0001F600-\U0001F64F"
+    "\U0001F300-\U0001F5FF"
+    "\U0001F680-\U0001F6FF"
+    "\U0001F900-\U0001F9FF"
+    "\U0001FA70-\U0001FAFF"
+    "\U00002702-\U000027B0"
+    "\U000024C2-\U0001F251"
+    "]+",
+    flags=re.UNICODE,
+)
+
+
+def _has_emoji(text: str) -> bool:
+    return bool(text and _EMOJI_PATTERN.search(text))
+
+
+def _count_links(html: str) -> int:
+    return len(_LINK_PATTERN.findall(html)) if html else 0
+
+
+def _word_count(html: str) -> int:
+    if not html:
+        return 0
+    clean = _HTML_TAG_PATTERN.sub(" ", html)
+    clean = _WHITESPACE_PATTERN.sub(" ", clean).strip()
+    return len(clean.split()) if clean else 0
+
+
+def _parse_iso_datetime(value: str | None) -> datetime | None:
+    """Parse an ISO datetime/date string and normalize naive values to UTC."""
+    if not value:
+        return None
+    try:
+        dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except (ValueError, TypeError):
+        return None
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=timezone.utc)
+    return dt
+
+
+def _summarize_lists(items: Any) -> list[dict]:
+    if not isinstance(items, list):
+        return []
+    results = []
+    for it in items:
+        if not isinstance(it, dict):
+            continue
+        id_ = it.get("id")
+        name = it.get("name")
+        type_ = it.get("type")
+        if id_ is None or name is None or type_ is None:
+            continue
+        results.append({"id": id_, "name": name, "type": type_, "users_count": it.get("users_count")})
+    return results
+
+
+def _extract_time_metrics(send_at: str | None, project_timezone: str | None) -> dict | None:
+    """Build time metrics from send_at timestamp."""
+    dt = _parse_iso_datetime(send_at)
+    if dt is None:
+        return None
+
+    metrics_dt = dt
+
+    if project_timezone and ZoneInfo is not None:
+        try:
+            local_dt = dt.astimezone(ZoneInfo(project_timezone))
+            metrics_dt = local_dt
+        except Exception:
+            pass
+
+    metrics: dict[str, Any] = {
+        "day_of_week": metrics_dt.strftime("%A"),
+        "hour_of_day": dt.hour,
+        "month": metrics_dt.strftime("%B"),
+        "year": metrics_dt.year,
+    }
+    if metrics_dt is not dt:
+        metrics["local_hour_of_day"] = metrics_dt.hour
+    return metrics
+
+
+def _extract_template_fields(templates: Any) -> dict[str, Any]:
+    """Extract locale, from, subject, preheader, mjml, and content_analysis from templates."""
+    fields: dict[str, Any] = {}
+    if not isinstance(templates, list) or not templates:
+        return fields
+
+    tmpl = templates[0]
+    if not isinstance(tmpl, dict):
+        return fields
+
+    locale = tmpl.get("locale")
+    if locale:
+        fields["locale"] = locale
+
+    data = tmpl.get("data")
+    if not isinstance(data, dict):
+        return fields
+
+    from_data = data.get("from")
+    if isinstance(from_data, dict):
+        fields["from"] = {"name": from_data.get("name"), "address": from_data.get("address")}
+
+    subject = data.get("subject", "")
+    preheader = data.get("preheader", "")
+    fields["subject"] = subject
+    fields["preheader"] = preheader
+    fields["mjml"] = data.get("mjml", "")
+
+    html_content = data.get("html", "")
+    content_to_analyze = html_content or data.get("mjml", "")
+    fields["content_analysis"] = {
+        "subject_length": len(subject),
+        "preheader_length": len(preheader),
+        "subject_has_emoji": _has_emoji(subject),
+        "preheader_has_emoji": _has_emoji(preheader),
+        "link_count": _count_links(html_content),
+        "word_count": _word_count(content_to_analyze),
+    }
+    return fields
+
+
+def _summarize_dict(source: Any, keys: list[str]) -> dict | None:
+    """Extract a subset of keys from a dict, or return None if source is not a dict."""
+    if not isinstance(source, dict):
+        return None
+    return {k: source.get(k) for k in keys}
+
+
+def extract_campaign_record(
+    campaign: dict, project_timezone: str | None = None
+) -> dict | None:
+    """Extract enriched record from a raw campaign API response.
+
+    Returns None if the campaign has no delivery data or zero sends.
+    """
+    delivery = campaign.get("delivery")
+    if not isinstance(delivery, dict):
+        return None
+
+    sent = delivery.get("sent", 0)
+    if sent <= 0:
+        return None
+
+    opens = delivery.get("opens", 0)
+    clicks = delivery.get("clicks", 0)
+
+    record: dict[str, Any] = {
+        "id": campaign.get("id"),
+        "name": campaign.get("name"),
+        "type": campaign.get("type"),
+        "channel": campaign.get("channel"),
+        "state": campaign.get("state"),
+        "send_at": campaign.get("send_at"),
+        "created_at": campaign.get("created_at"),
+        "updated_at": campaign.get("updated_at"),
+        "deleted_at": campaign.get("deleted_at"),
+        "delivery": {"sent": sent, "opens": opens, "clicks": clicks},
+        "analytics": {
+            "open_rate": round((opens / sent) * 100, 2),
+            "click_rate": round((clicks / sent) * 100, 2),
+            "click_to_open_rate": round((clicks / opens) * 100, 2) if opens > 0 else 0,
+        },
+        "tags": campaign.get("tags", []),
+    }
+
+    provider = _summarize_dict(campaign.get("provider"), ["id", "type", "name", "group"])
+    if provider:
+        record["provider"] = provider
+
+    subscription = _summarize_dict(campaign.get("subscription"), ["id", "name", "channel"])
+    if subscription:
+        record["subscription"] = subscription
+
+    lists_summary = _summarize_lists(campaign.get("lists"))
+    if lists_summary:
+        record["lists"] = lists_summary
+    exclusion_summary = _summarize_lists(campaign.get("exclusion_lists"))
+    if exclusion_summary:
+        record["exclusion_lists"] = exclusion_summary
+
+    time_metrics = _extract_time_metrics(campaign.get("send_at"), project_timezone)
+    if time_metrics:
+        record["time_metrics"] = time_metrics
+
+    record.update(_extract_template_fields(campaign.get("templates")))
+
+    return record
+
+
+def is_within_date_range(
+    date_str: str | None,
+    *,
+    days: int | None = None,
+    after: str | None = None,
+    before: str | None = None,
+) -> bool:
+    """Check if a date string falls within the given range.
+
+    Supports three modes:
+    - days: last N days from now
+    - after/before: explicit ISO date boundaries
+    - combined: after + before for a window
+    """
+    dt = _parse_iso_datetime(date_str)
+    if dt is None:
+        return False
+
+    if days is not None:
+        threshold = datetime.now(timezone.utc) - timedelta(days=days)
+        if dt < threshold:
+            return False
+
+    if after is not None:
+        after_dt = _parse_iso_datetime(after)
+        if after_dt is None:
+            return False
+        if dt < after_dt:
+            return False
+
+    if before is not None:
+        before_dt = _parse_iso_datetime(before)
+        if before_dt is None:
+            return False
+        if dt > before_dt:
+            return False
+
+    return True
+
+
+def sanitize_filename(subject: str, date_str: str) -> str:
+    """Create a sanitized filename from subject and date."""
+    date_obj = _parse_iso_datetime(date_str)
+    date_formatted = date_obj.strftime("%Y-%m-%d") if date_obj else "unknown-date"
+
+    clean = re.sub(r"[^\w\s-]", "", subject)
+    clean = re.sub(r"[-\s]+", "-", clean)
+    clean = clean.strip("-").lower()
+    if len(clean) > 50:
+        clean = clean[:50].rstrip("-")
+
+    return f"blast_{date_formatted}_{clean}.html" if clean else f"blast_{date_formatted}.html"
+