ermes-cli 1.0.0__py3-none-any.whl

ermes_cli/commands/lists.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+import json as json_lib
+from typing import Optional
+import typer
+from ermes_cli.client import ErmesAPIError
+from ermes_cli.rules import normalize_rule_values
+
+lists_app = typer.Typer(help="Manage lists", no_args_is_help=True)
+COLUMNS = ["id", "name", "type", "state", "users_count", "tags"]
+
+
+def _get_deps():
+    from ermes_cli.main import get_client, state
+    from ermes_cli.output import render, render_detail, render_message
+    return get_client(), state, render, render_detail, render_message
+
+
+@lists_app.command("list")
+def lists_list(
+    list_type: Optional[str] = typer.Option(None, "--type", help="Filter by type"),
+    limit: int = typer.Option(100, "--limit", help="Max results (0 = all)"),
+):
+    """List lists."""
+    client, st, render, _, _ = _get_deps()
+    params = {}
+    if list_type:
+        params["filter[type]"] = list_type
+    try:
+        data = client.get_paginated("/lists", params=params, limit=limit)
+        render(data, columns=COLUMNS, use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@lists_app.command("get")
+def lists_get(list_id: int = typer.Argument(..., help="List ID")):
+    """Get list details."""
+    client, st, _, render_detail, _ = _get_deps()
+    try:
+        data = client.get(f"/lists/{list_id}")
+        render_detail(data, use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@lists_app.command("create")
+def lists_create(
+    name: str = typer.Option(..., "--name", help="List name"),
+    list_type: str = typer.Option(..., "--type", help="static or dynamic"),
+    rule: Optional[str] = typer.Option(None, "--rule", help="Rule as JSON (for dynamic lists)"),
+):
+    """Create a list."""
+    client, st, _, render_detail, _ = _get_deps()
+    body: dict = {"name": name, "type": list_type}
+    if rule:
+        try:
+            body["rule"] = normalize_rule_values(json_lib.loads(rule))
+        except json_lib.JSONDecodeError as e:
+            typer.echo(f"Invalid JSON for --rule: {e}", err=True)
+            raise typer.Exit(code=1)
+    try:
+        data = client.post("/lists", json=body)
+        render_detail(data, use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@lists_app.command("update")
+def lists_update(
+    list_id: int = typer.Argument(..., help="List ID"),
+    name: Optional[str] = typer.Option(None, "--name"),
+):
+    """Update a list."""
+    client, st, _, render_detail, _ = _get_deps()
+    body = {}
+    if name:
+        body["name"] = name
+    if not body:
+        typer.echo("Nothing to update. Provide at least one option.", err=True)
+        raise typer.Exit(code=1)
+    try:
+        data = client.patch(f"/lists/{list_id}", json=body)
+        render_detail(data, use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@lists_app.command("delete")
+def lists_delete(list_id: int = typer.Argument(..., help="List ID")):
+    """Delete a list."""
+    client, st, _, _, render_message = _get_deps()
+    try:
+        client.delete(f"/lists/{list_id}")
+        render_message(f"List {list_id} deleted.", use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@lists_app.command("duplicate")
+def lists_duplicate(list_id: int = typer.Argument(..., help="List ID")):
+    """Duplicate a list."""
+    client, st, _, render_detail, _ = _get_deps()
+    try:
+        data = client.post(f"/lists/{list_id}/duplicate")
+        render_detail(data, use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@lists_app.command("users")
+def lists_users(list_id: int = typer.Argument(..., help="List ID"), limit: int = typer.Option(100, "--limit")):
+    """List users in a list."""
+    client, st, render, _, _ = _get_deps()
+    try:
+        data = client.get_paginated(f"/lists/{list_id}/users", limit=limit)
+        render(data, columns=["id", "email", "external_id"], use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@lists_app.command("recount")
+def lists_recount(list_id: int = typer.Argument(..., help="List ID")):
+    """Trigger a recount of list users."""
+    client, st, _, render_detail, _ = _get_deps()
+    try:
+        data = client.post(f"/lists/{list_id}/recount")
+        render_detail(data, use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)

ermes_cli/commands/metrics.py

@@ -0,0 +1,398 @@
+"""`ermes metrics` — parity with the UI Metrics view.
+
+Hits `/api/client/metrics` (the same endpoint the UI uses through admin
+scope; sk_ keys reach it via the secret-scope leg of the client router).
+Returns the per-campaign breakdown plus an aggregate summary plus the
+data freshness timestamp.
+
+Default behavior matches the UI:
+  - type=trigger
+  - channel=email
+  - last 7 days, ending yesterday (pass --end to include today's partial row)
+  - sorted by sends desc
+  - max 90-day range, capped at 100 rows server-side
+
+Channels: the endpoint filters on `campaigns.channel` and accepts exactly
+`email` or `push` (lowercase — anything else is a 400). Omitting the param
+means `email`, which is why a push-only project used to look empty. There is
+no server-side "both channels" mode, so `--channel all` here issues the two
+requests and prints two labelled blocks.
+
+Push rows carry `opens`/`bounces`/`complaints` (and the rates derived from
+them) as hard zeros — push has no open or bounce event — so the push table
+renders the UI's Sent / Delivered / Failed / Clicks columns instead:
+  - Delivered = `sends`
+  - Sent      = `sends + failed`
+  - Clicks    = `clicks` (a push must be tapped, so opens would equal clicks)
+
+`aggregated_through` is the newest local day the hourly rollup has marked
+complete (re-read after its own midnight) that has data for the requested
+channel+type. Today's row — and yesterday's, until the first run after local
+midnight — is a partial "so far" number: returned, but it never moves
+`aggregated_through`. So a window ending today includes partial data, and one
+past today is empty. Dates are passed through verbatim; the empty-state message
+just surfaces the frontier so an empty result is legible.
+
+JSON output: `--json` is a **root** flag (`ermes --json metrics …`), NOT an
+option on this command — `ermes metrics --json` exits with `No such option`.
+Per-campaign rows live under **`results`**, not `campaigns`/`rows`, next to
+`channel`, `summary`, `truncated` and `aggregated_through`. `--channel all`
+nests instead: `{"channel": "all", "channels": {"email": {…}, "push": {…}}}`,
+so a consumer has to branch on `channel` before reaching for `results`.
+
+Which PROJECT this queries is resolved by `config.resolve_profile()`, which
+honours `ERMES_PROJECT` — so `ERMES_PROJECT=224 ermes metrics …` reads project
+224 without disturbing the on-disk active project (useful when another session
+is working in a different one). `whoami` reports that same effective project
+via `config.get_effective_project()`.
+"""
+
+from __future__ import annotations
+
+from datetime import date, timedelta
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from ermes_cli.client import ErmesAPIError
+
+metrics_app = typer.Typer(
+    help="Campaign metrics (mirrors the UI Metrics view)",
+    no_args_is_help=False,
+    invoke_without_command=True,
+)
+
+console = Console()
+
+_VALID_TYPES = {"trigger", "blast", "all"}
+
+# The server accepts only these two (CampaignMetricsController); "all" is a
+# CLI-side convenience that fans out into one request per channel.
+_SERVER_CHANNELS = ("email", "push")
+_VALID_CHANNELS = {*_SERVER_CHANNELS, "all"}
+
+
+def _format_int(value: int | float | None) -> str:
+    if value is None:
+        return "—"
+    try:
+        return f"{int(value):,}"
+    except (TypeError, ValueError):
+        return str(value)
+
+
+def _format_pct(value: int | float | None) -> str:
+    if value is None:
+        return "—"
+    try:
+        # API returns rates as percentages already (e.g. 23.4 means 23.4%).
+        return f"{float(value):.2f}%"
+    except (TypeError, ValueError):
+        return str(value)
+
+
+def _sent(row: dict) -> int | None:
+    """Push "Sent" = delivered + failed (the UI's naming, DEV-1099).
+
+    `sends` alone is Delivered; a campaign that failed every push still has
+    real activity, so the attempted total is the honest headline number.
+    """
+    sends, failed = row.get("sends"), row.get("failed")
+    if sends is None and failed is None:
+        return None
+    return int(sends or 0) + int(failed or 0)
+
+
+def _email_table(results: list, summary: dict, title: str) -> Table:
+    table = Table(title=title)
+    table.add_column("ID", justify="right")
+    table.add_column("Campaign", overflow="fold")
+    table.add_column("Sends", justify="right")
+    table.add_column("Opens", justify="right")
+    table.add_column("Clicks", justify="right")
+    table.add_column("Bounces", justify="right")
+    table.add_column("Spam", justify="right")
+    table.add_column("Open %", justify="right")
+    table.add_column("Click %", justify="right")
+    table.add_column("CTOR %", justify="right")
+
+    for row in results:
+        table.add_row(
+            str(row.get("campaign_id", "")),
+            str(row.get("name") or ""),
+            _format_int(row.get("sends")),
+            _format_int(row.get("opens")),
+            _format_int(row.get("clicks")),
+            _format_int(row.get("bounces")),
+            _format_int(row.get("complaints")),
+            _format_pct(row.get("open_rate")),
+            _format_pct(row.get("click_rate")),
+            _format_pct(row.get("ctor")),
+        )
+
+    if results:
+        table.add_section()
+        table.add_row(
+            "",
+            f"[bold]Summary ({summary.get('campaign_count', 0)} campaigns)[/bold]",
+            _format_int(summary.get("sends")),
+            _format_int(summary.get("opens")),
+            _format_int(summary.get("clicks")),
+            _format_int(summary.get("bounces")),
+            _format_int(summary.get("complaints")),
+            _format_pct(summary.get("open_rate")),
+            _format_pct(summary.get("click_rate")),
+            _format_pct(summary.get("ctor")),
+        )
+    return table
+
+
+def _push_table(results: list, summary: dict, title: str) -> Table:
+    """Push-only columns.
+
+    Opens / Open % / CTOR / Bounces / Spam are structurally zero for push
+    (there is no open or bounce event) — printing them reads as breakage, so
+    they are omitted entirely rather than shown as 0.
+    """
+    table = Table(title=title)
+    table.add_column("ID", justify="right")
+    table.add_column("Campaign", overflow="fold")
+    table.add_column("Sent", justify="right")
+    table.add_column("Delivered", justify="right")
+    table.add_column("Failed", justify="right")
+    table.add_column("Clicks", justify="right")
+    table.add_column("Click %", justify="right")
+
+    for row in results:
+        table.add_row(
+            str(row.get("campaign_id", "")),
+            str(row.get("name") or ""),
+            _format_int(_sent(row)),
+            _format_int(row.get("sends")),
+            _format_int(row.get("failed")),
+            _format_int(row.get("clicks")),
+            _format_pct(row.get("click_rate")),
+        )
+
+    if results:
+        table.add_section()
+        table.add_row(
+            "",
+            f"[bold]Summary ({summary.get('campaign_count', 0)} campaigns)[/bold]",
+            _format_int(_sent(summary)),
+            _format_int(summary.get("sends")),
+            _format_int(summary.get("failed")),
+            _format_int(summary.get("clicks")),
+            _format_pct(summary.get("click_rate")),
+        )
+    return table
+
+
+def _empty_message(channel: str, kind: str, start: str, freshness: str | None) -> str:
+    """Explain an empty window without asserting a cause we can't know.
+
+    The old copy claimed "no email campaigns sent", which is wrong whenever a
+    channel filter is in play, or when the requested window simply sits past
+    the rollup frontier. Days after `aggregated_through` are partial (or not
+    rolled up yet), so a window that *starts* after it can be empty for that
+    reason alone.
+    """
+    scope = f"channel={channel}, type={kind}"
+    # The complaint this flag exists for: a push-only project reads as "no
+    # data at all" under the (default) email filter.
+    hint = (
+        " If this project sends push, retry with --channel push."
+        if channel == "email"
+        else ""
+    )
+
+    if freshness is None:
+        return (
+            f"[yellow]No {channel} metrics in this window.[/yellow] "
+            f"No completed day is recorded for {scope} in this project "
+            f"(aggregated_through is null).{hint}"
+        )
+
+    base = (
+        f"[yellow]No {channel} metrics in this window[/yellow] "
+        f"(data aggregated through {freshness}; {scope})."
+    )
+    if start > freshness:
+        return (
+            f"{base} The whole window starts after {freshness}: those days "
+            "are partial (refreshed hourly) and may have no sends yet."
+        )
+    return base + hint
+
+
+def _render_table(data: dict, kind: str, start: str, end: str, channel: str) -> None:
+    results = data.get("results") or []
+    summary = data.get("summary") or {}
+    freshness = data.get("aggregated_through")
+    truncated = bool(data.get("truncated"))
+
+    # Title wording for email is deliberately unchanged from the pre-channel
+    # CLI so the default view stays byte-identical for existing scripts.
+    title = (
+        f"{channel.capitalize()} metrics — type={kind}, {start} → {end}"
+        f"  (data through {freshness or 'n/a'})"
+    )
+    build = _push_table if channel == "push" else _email_table
+    console.print(build(results, summary, title))
+
+    if not results:
+        console.print(_empty_message(channel, kind, start, freshness))
+    if truncated:
+        console.print(
+            "[yellow]Note:[/yellow] result set was truncated server-side "
+            "(>100 campaigns). Narrow the date range or filter by type."
+        )
+
+
+@metrics_app.callback()
+def metrics(
+    ctx: typer.Context,
+    type_: str = typer.Option(
+        "trigger",
+        "--type",
+        "-t",
+        help="Campaign type: trigger | blast | all.",
+        show_default=True,
+    ),
+    start: Optional[str] = typer.Option(
+        None,
+        "--start",
+        "-s",
+        help="Start date YYYY-MM-DD (default: 7 days before --end, or 7 days ago).",
+    ),
+    end: Optional[str] = typer.Option(
+        None,
+        "--end",
+        "-e",
+        help="End date YYYY-MM-DD (default: yesterday; today is partial).",
+    ),
+    days: Optional[int] = typer.Option(
+        None,
+        "--days",
+        "-d",
+        help="Convenience: the N days before today (ending yesterday). Overrides --start/--end.",
+    ),
+    channel: str = typer.Option(
+        "email",
+        "--channel",
+        "-c",
+        help=(
+            "Channel: email | push | all. 'all' runs one request per channel "
+            "and prints two blocks (the API has no combined mode)."
+        ),
+        show_default=True,
+    ),
+) -> None:
+    """Show campaign metrics for the active project.
+
+    With no arguments: last 7 days, type=trigger, channel=email — matches the
+    UI's default view.
+    """
+    # If a subcommand was invoked (none defined today, but future-proof), skip
+    # the top-level fetch.
+    if ctx.invoked_subcommand is not None:
+        return
+
+    if type_ not in _VALID_TYPES:
+        typer.echo(
+            f"--type must be one of {sorted(_VALID_TYPES)}, got {type_!r}",
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    # The API rejects a non-lowercase channel with a 400, so fold the case here
+    # rather than making the user guess.
+    channel = (channel or "").strip().lower()
+    if channel not in _VALID_CHANNELS:
+        typer.echo(
+            f"--channel must be one of {sorted(_VALID_CHANNELS)}, got {channel!r}",
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    # Default windows end yesterday, like the UI: today's row is a partial
+    # "so far" number (refreshed hourly) that would dilute the rates.
+    today = date.today()
+    yesterday = (today - timedelta(days=1)).isoformat()
+    if days is not None:
+        if days <= 0:
+            typer.echo("--days must be a positive integer", err=True)
+            raise typer.Exit(code=2)
+        start = (today - timedelta(days=days)).isoformat()
+        end = yesterday
+    elif end is None:
+        start = start or (today - timedelta(days=7)).isoformat()
+        # `--start <today>` alone still asks for today's partial row.
+        end = max(start, yesterday)
+    elif start is None:
+        start = (date.fromisoformat(end) - timedelta(days=7)).isoformat()
+
+    from ermes_cli.main import get_client, state
+
+    wanted = _SERVER_CHANNELS if channel == "all" else (channel,)
+    client = get_client()
+    fetched: dict[str, dict] = {}
+    errors: dict[str, str] = {}
+    for chan in wanted:
+        try:
+            resp = client.get(
+                "/metrics",
+                params={"type": type_, "start": start, "end": end, "channel": chan},
+            )
+            fetched[chan] = resp or {}
+        except ErmesAPIError as exc:
+            errors[chan] = str(exc)
+            # Under --channel all the channels are independent requests: one failing
+            # is no reason to throw away the other's data, which the user has already
+            # paid for. Name the channel only when fanning out, so the single-channel
+            # message stays exactly what it has always been.
+            label = (
+                f"Metrics fetch failed for channel={chan}"
+                if len(wanted) > 1
+                else "Metrics fetch failed"
+            )
+            typer.echo(f"{label}: {exc}", err=True)
+
+    # Nothing at all came back — same outcome as before for the single-channel case.
+    if not fetched:
+        raise typer.Exit(code=1)
+
+    if state.use_json:
+        import json
+
+        if channel == "all":
+            # Two independent payloads — nesting them keeps each one's summary
+            # and aggregated_through unambiguous instead of silently merging
+            # incomparable channels.
+            payload: dict = {"channel": "all", "channels": fetched}
+        else:
+            # Response keys first: `channel` is the CLI's own annotation and must win
+            # over any same-named key the server might grow later.
+            payload = {**fetched[channel], "channel": channel}
+        if errors:
+            payload["errors"] = errors
+        typer.echo(json.dumps(payload, indent=2, default=str))
+        if errors:
+            raise typer.Exit(code=1)
+        return
+
+    if channel == "all":
+        console.print(
+            "[dim]--channel all is client-side: one request per channel, two "
+            "blocks. The API has no combined mode, and the two channels' "
+            "metrics are not comparable (push has no opens/bounces).[/dim]"
+        )
+    for chan in wanted:
+        if chan in fetched:
+            _render_table(fetched[chan], type_, start, end, chan)
+
+    # Partial success is still a failure for a script: render what we have, exit non-zero.
+    if errors:
+        raise typer.Exit(code=1)