ermes-cli 1.0.0__py3-none-any.whl

ermes_cli/commands/export.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import json as json_lib
+from typing import Any, Optional
+
+import typer
+
+from ermes_cli.client import ErmesAPIError, ErmesClient
+from ermes_cli.export_utils import (
+    extract_campaign_record,
+    is_within_date_range,
+)
+
+export_app = typer.Typer(
+    help="Export campaign data for analysis",
+    no_args_is_help=True,
+)
+
+
+def _get_deps():
+    from ermes_cli.main import get_client, state
+    from ermes_cli.output import render_message
+    return get_client(), state, render_message
+
+
+def _fetch_campaigns(
+    client: ErmesClient,
+    campaign_type: str | None,
+    status: str | None,
+) -> list[dict]:
+    """Fetch campaigns with optional server-side filters."""
+    params: dict = {}
+    filter_obj: dict = {}
+    if campaign_type:
+        filter_obj["type"] = campaign_type
+    if status:
+        filter_obj["state"] = status
+    if filter_obj:
+        params["filter"] = json_lib.dumps(filter_obj)
+    return client.get_paginated("/campaigns", params=params, limit=0)
+
+
+def _apply_client_filters(
+    campaigns: list[dict],
+    *,
+    days: int | None,
+    after: str | None,
+    before: str | None,
+    limit: int,
+) -> list[dict]:
+    """Apply date filtering, zero-send removal, and limit."""
+    if days is not None or after is not None or before is not None:
+        campaigns = [
+            c for c in campaigns
+            if is_within_date_range(
+                c.get("send_at"),
+                days=days, after=after, before=before,
+            )
+        ]
+    campaigns = [
+        c for c in campaigns
+        if (c.get("delivery") or {}).get("sent", 0) > 0
+    ]
+    if limit > 0:
+        campaigns = campaigns[:limit]
+    return campaigns
+
+
+def _enrich_campaigns(
+    client: ErmesClient,
+    campaigns: list[dict],
+    project_timezone: str | None,
+) -> list[dict]:
+    """Fetch details and enrich each campaign."""
+    enriched = []
+    skipped = 0
+    for c in campaigns:
+        try:
+            detail = client.get(f"/campaigns/{c['id']}")
+            record = extract_campaign_record(detail, project_timezone)
+            if record:
+                enriched.append(record)
+        except ErmesAPIError:
+            skipped += 1
+            continue
+    if skipped:
+        import sys
+        print(f"Warning: {skipped}/{len(campaigns)} campaigns skipped due to API errors", file=sys.stderr)
+    return enriched
+
+
+def _build_metadata(
+    enriched: list[dict],
+    project_timezone: str | None,
+) -> dict[str, Any]:
+    """Build summary metadata for the export."""
+    metadata: dict[str, Any] = {
+        "count": len(enriched),
+        "project_timezone": project_timezone,
+    }
+    if not enriched:
+        return metadata
+
+    open_rates = [r["analytics"]["open_rate"] for r in enriched]
+    click_rates = [r["analytics"]["click_rate"] for r in enriched]
+    metadata["avg_open_rate"] = round(
+        sum(open_rates) / len(open_rates), 2,
+    )
+    metadata["avg_click_rate"] = round(
+        sum(click_rates) / len(click_rates), 2,
+    )
+    send_dates = [
+        r["send_at"] for r in enriched if r.get("send_at")
+    ]
+    if send_dates:
+        metadata["date_range"] = {
+            "from": min(send_dates), "to": max(send_dates),
+        }
+    return metadata
+
+
+def _write_or_print(
+    json_str: str,
+    output: str | None,
+    count: int,
+    render_message,
+    use_json: bool,
+):
+    """Write JSON to file or print to stdout."""
+    if output:
+        with open(output, "w", encoding="utf-8") as f:
+            f.write(json_str)
+        render_message(
+            f"Exported {count} campaigns to {output}",
+            use_json=use_json,
+        )
+    else:
+        print(json_str)
+
+
+@export_app.command("campaigns")
+def export_campaigns(
+    campaign_type: Optional[str] = typer.Option(
+        None, "--type", help="Filter: blast|trigger",
+    ),
+    status: Optional[str] = typer.Option(
+        None, "--status", help="Filter by state",
+    ),
+    days: Optional[int] = typer.Option(
+        None, "--days", help="Only last N days",
+    ),
+    after: Optional[str] = typer.Option(
+        None, "--after", help="Sent after (ISO date)",
+    ),
+    before: Optional[str] = typer.Option(
+        None, "--before", help="Sent before (ISO date)",
+    ),
+    limit: int = typer.Option(
+        0, "--limit", help="Max campaigns (0 = all)",
+    ),
+    output: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Write JSON to file",
+    ),
+):
+    """Export enriched campaign JSON with analytics."""
+    client, st, render_message = _get_deps()
+    try:
+        project = client.get("/")
+        tz = (
+            project.get("timezone")
+            if isinstance(project, dict) else None
+        )
+        campaigns = _fetch_campaigns(client, campaign_type, status)
+        campaigns = _apply_client_filters(
+            campaigns,
+            days=days, after=after, before=before, limit=limit,
+        )
+        enriched = _enrich_campaigns(client, campaigns, tz)
+        result = {
+            "metadata": _build_metadata(enriched, tz),
+            "campaigns": enriched,
+        }
+        json_str = json_lib.dumps(
+            result, indent=2, ensure_ascii=False, default=str,
+        )
+        _write_or_print(
+            json_str, output, len(enriched),
+            render_message, st.use_json,
+        )
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@export_app.command("html")
+def export_html(
+    campaign_id: int = typer.Argument(
+        ..., help="Campaign ID to extract HTML from",
+    ),
+    output: Optional[str] = typer.Option(
+        None, "--output", "-o", help="Write HTML to file",
+    ),
+):
+    """Extract the HTML template from a single campaign."""
+    client, st, render_message = _get_deps()
+    try:
+        detail = client.get(f"/campaigns/{campaign_id}")
+        templates = detail.get("templates", [])
+        if not templates:
+            typer.echo("Campaign has no templates.", err=True)
+            raise typer.Exit(code=1)
+
+        tmpl_data = templates[0].get("data", {})
+        html = (
+            tmpl_data.get("html", "") or tmpl_data.get("mjml", "")
+        )
+        if not html:
+            typer.echo("No HTML or MJML content.", err=True)
+            raise typer.Exit(code=1)
+
+        if output:
+            with open(output, "w", encoding="utf-8") as f:
+                f.write(html)
+            render_message(
+                f"HTML saved to {output}", use_json=st.use_json,
+            )
+        elif st.use_json:
+            print(json_lib.dumps({
+                "campaign_id": campaign_id,
+                "subject": tmpl_data.get("subject", ""),
+                "html": html,
+            }, indent=2, ensure_ascii=False))
+        else:
+            print(html)
+
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)

ermes_cli/commands/ingest.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+import json as json_lib
+from typing import Optional
+import typer
+from ermes_cli.client import ErmesAPIError
+
+ingest_app = typer.Typer(help="Ingest data (identify users, post events, alias)", no_args_is_help=True)
+
+
+def _get_deps():
+    from ermes_cli.main import get_client, state
+    from ermes_cli.output import render_message
+    return get_client(), state, render_message
+
+
+def _require_identity(external_id: str | None, anonymous_id: str | None) -> None:
+    """Exit with error if neither identity field is provided."""
+    if not external_id and not anonymous_id:
+        typer.echo("Error: at least one of --external-id or --anonymous-id is required.", err=True)
+        raise typer.Exit(code=1)
+
+
+def _build_body(fields: dict) -> dict:
+    """Build a request body from optional fields, parsing 'data' as JSON."""
+    body: dict = {}
+    for key, value in fields.items():
+        if value is None:
+            continue
+        if key == "data":
+            try:
+                body["data"] = json_lib.loads(value)
+            except json_lib.JSONDecodeError as e:
+                typer.echo(f"Invalid JSON for --data: {e}", err=True)
+                raise typer.Exit(code=1)
+        else:
+            body[key] = value
+    return body
+
+
+@ingest_app.command("identify")
+def ingest_identify(
+    external_id: Optional[str] = typer.Option(None, "--external-id", help="User external ID"),
+    anonymous_id: Optional[str] = typer.Option(None, "--anonymous-id", help="Anonymous tracking ID"),
+    email: Optional[str] = typer.Option(None, "--email", help="Email address"),
+    phone: Optional[str] = typer.Option(None, "--phone", help="Phone number"),
+    timezone: Optional[str] = typer.Option(None, "--timezone", help="IANA timezone"),
+    locale: Optional[str] = typer.Option(None, "--locale", help="Locale code"),
+    data: Optional[str] = typer.Option(None, "--data", help="Custom attributes as JSON string"),
+):
+    """Identify or update a user."""
+    _require_identity(external_id, anonymous_id)
+    client, st, render_message = _get_deps()
+    body = _build_body({
+        "external_id": external_id, "anonymous_id": anonymous_id,
+        "email": email, "phone": phone, "timezone": timezone,
+        "locale": locale, "data": data,
+    })
+    try:
+        client.post("/identify", json=body)
+        render_message("User identified.", use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@ingest_app.command("event")
+def ingest_event(
+    external_id: Optional[str] = typer.Option(None, "--external-id", help="User external ID"),
+    anonymous_id: Optional[str] = typer.Option(None, "--anonymous-id", help="Anonymous tracking ID"),
+    name: str = typer.Option(..., "--name", help="Event name"),
+    data: Optional[str] = typer.Option(None, "--data", help="Event properties as JSON string"),
+):
+    """Post a user event."""
+    _require_identity(external_id, anonymous_id)
+    client, st, render_message = _get_deps()
+    event = _build_body({
+        "external_id": external_id, "anonymous_id": anonymous_id,
+        "name": name, "data": data,
+    })
+    try:
+        client.post("/events", json=[event])
+        render_message("Event recorded.", use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@ingest_app.command("alias")
+def ingest_alias(
+    external_id: str = typer.Option(..., "--external-id", help="User external ID"),
+    anonymous_id: str = typer.Option(..., "--anonymous-id", help="Anonymous tracking ID"),
+):
+    """Link an anonymous ID to an external ID."""
+    client, st, render_message = _get_deps()
+    body = {"external_id": external_id, "anonymous_id": anonymous_id}
+    try:
+        client.post("/alias", json=body)
+        render_message("Alias created.", use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)

ermes_cli/commands/journeys.py

@@ -0,0 +1,182 @@
+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
+
+journeys_app = typer.Typer(help="Manage journeys", no_args_is_help=True)
+COLUMNS = ["id", "name", "published", "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
+
+
+@journeys_app.command("list")
+def journeys_list(
+    limit: int = typer.Option(100, "--limit", help="Max results (0 = all)"),
+):
+    """List journeys."""
+    client, st, render, _, _ = _get_deps()
+    try:
+        data = client.get_paginated("/journeys", 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)
+
+
+@journeys_app.command("get")
+def journeys_get(journey_id: int = typer.Argument(..., help="Journey ID")):
+    """Get journey details."""
+    client, st, _, render_detail, _ = _get_deps()
+    try:
+        data = client.get(f"/journeys/{journey_id}")
+        render_detail(data, use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@journeys_app.command("create")
+def journeys_create(
+    name: str = typer.Option(..., "--name", help="Journey name"),
+    published: bool = typer.Option(False, "--published", help="Publish the journey"),
+    description: Optional[str] = typer.Option(None, "--description", help="Journey description"),
+):
+    """Create a journey."""
+    client, st, _, render_detail, _ = _get_deps()
+    body: dict = {"name": name, "published": published}
+    if description is not None:
+        body["description"] = description
+    try:
+        data = client.post("/journeys", 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)
+
+
+@journeys_app.command("update")
+def journeys_update(
+    journey_id: int = typer.Argument(..., help="Journey ID"),
+    name: str = typer.Option(..., "--name", help="Journey name (required by the API on update)"),
+    published: Optional[bool] = typer.Option(None, "--published", help="Publish or unpublish"),
+    description: Optional[str] = typer.Option(None, "--description", help="Journey description"),
+):
+    """Update a journey."""
+    client, st, _, render_detail, _ = _get_deps()
+    body: dict = {"name": name}
+    if published is not None:
+        body["published"] = published
+    if description is not None:
+        body["description"] = description
+    try:
+        data = client.patch(f"/journeys/{journey_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)
+
+
+@journeys_app.command("delete")
+def journeys_delete(journey_id: int = typer.Argument(..., help="Journey ID")):
+    """Delete a journey."""
+    client, st, _, _, render_message = _get_deps()
+    try:
+        client.delete(f"/journeys/{journey_id}")
+        render_message(f"Journey {journey_id} deleted.", use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@journeys_app.command("duplicate")
+def journeys_duplicate(journey_id: int = typer.Argument(..., help="Journey ID")):
+    """Duplicate a journey."""
+    client, st, _, render_detail, _ = _get_deps()
+    try:
+        data = client.post(f"/journeys/{journey_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)
+
+
+@journeys_app.command("steps")
+def journeys_steps(journey_id: int = typer.Argument(..., help="Journey ID")):
+    """Get journey steps."""
+    client, st, _, render_detail, _ = _get_deps()
+    try:
+        data = client.get(f"/journeys/{journey_id}/steps")
+        render_detail(data, use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@journeys_app.command("trigger")
+def journeys_trigger(
+    journey_id: int = typer.Argument(..., help="Journey ID"),
+    entrance: int = typer.Option(..., "--entrance", help="Entrance step ID"),
+    external_id: str = typer.Option(..., "--external-id", help="User external ID"),
+    event: Optional[str] = typer.Option(None, "--event", help="Event data as JSON"),
+):
+    """Trigger a journey for a user."""
+    client, st, _, render_detail, _ = _get_deps()
+    body: dict = {"entrance_id": entrance, "user": {"external_id": external_id}}
+    if event:
+        try:
+            body["event"] = json_lib.loads(event)
+        except json_lib.JSONDecodeError as e:
+            typer.echo(f"Invalid JSON for --event: {e}", err=True)
+            raise typer.Exit(code=1)
+    try:
+        data = client.post(f"/journeys/{journey_id}/trigger", 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)
+
+
+@journeys_app.command("exit-user")
+def journeys_exit_user(
+    journey_id: int = typer.Argument(..., help="Journey ID"),
+    user: str = typer.Option(..., "--user", help="User external ID"),
+    entrance: Optional[int] = typer.Option(None, "--entrance", help="Entrance ID"),
+):
+    """Exit a user from a journey (or a specific entrance)."""
+    client, st, _, _, render_message = _get_deps()
+    if entrance is not None:
+        path = f"/journeys/{journey_id}/entrances/{entrance}/users/{user}"
+    else:
+        path = f"/journeys/{journey_id}/users/{user}"
+    try:
+        client.delete(path)
+        render_message(f"User {user} exited from journey {journey_id}.", use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@journeys_app.command("steps-update")
+def journeys_steps_update(
+    journey_id: int = typer.Argument(..., help="Journey ID"),
+    steps: str = typer.Option(..., "--steps", help="Steps JSON"),
+):
+    """Update journey steps."""
+    client, st, _, render_detail, _ = _get_deps()
+    try:
+        body = normalize_rule_values(json_lib.loads(steps))
+    except json_lib.JSONDecodeError as e:
+        typer.echo(f"Invalid JSON for --steps: {e}", err=True)
+        raise typer.Exit(code=1)
+    try:
+        data = client.put(f"/journeys/{journey_id}/steps", 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)

ermes_cli/commands/keys.py

@@ -0,0 +1,113 @@
+"""`ermes keys` — manage a project's API keys.
+
+Routed through the admin JWT at `/api/admin/projects/:id/keys`: since DEV-2260
+`/api/client/keys` rejects `sk_` keys, so a leaked CLI key cannot mint more keys.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from ermes_cli import admin_api, write_mode
+from ermes_cli.errors import WriteBlockedError
+
+keys_app = typer.Typer(help="Manage API keys (requires `ermes login`)", no_args_is_help=True)
+COLUMNS = ["id", "name", "scope", "role", "created_at"]
+
+
+def _call(method: str, path: str = "", json: dict | None = None, params: dict | None = None):
+    """One admin-JWT request against the effective project's keys. Exits 1 on any failure."""
+    from ermes_cli.commands.auth_cmds import _ensure_admin_session
+    from ermes_cli.config import get_effective_project
+    from ermes_cli.main import state
+
+    pid, _, source = get_effective_project(state.profile_name)
+    if pid is None:
+        typer.echo(
+            f"keys: no project identity ({source}). Use `ermes use <project>` or ERMES_PROJECT.",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+    if method != "GET":
+        try:
+            write_mode.assert_writes_allowed(method, f"/api/admin/projects/{pid}/keys{path}")
+        except WriteBlockedError as exc:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(code=1)
+    base, session = _ensure_admin_session()
+    url = f"{base.rstrip('/')}/api/admin/projects/{pid}/keys{path}"
+    try:
+        return admin_api.request(method, url, session.ermes_access_token, json=json, params=params)
+    except admin_api.AdminAPIError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1)
+
+
+def _out():
+    from ermes_cli.main import state
+    from ermes_cli.output import render, render_detail, render_message
+
+    return state, render, render_detail, render_message
+
+
+@keys_app.command("list")
+def keys_list(limit: int = typer.Option(100, "--limit", help="Max results")):
+    """List API keys of the active project."""
+    st, render, _, _ = _out()
+    data = _call("GET", params={"limit": limit})
+    rows = data.get("results", data) if isinstance(data, dict) else data
+    render(rows or [], columns=COLUMNS, use_json=st.use_json)
+
+
+@keys_app.command("create")
+def keys_create(
+    name: str = typer.Option(..., "--name", help="Key name"),
+    scope: str = typer.Option(..., "--scope", help="Key scope: public or secret"),
+    description: Optional[str] = typer.Option(None, "--description", help="Key description"),
+    role: Optional[str] = typer.Option(None, "--role", help="Project role: support, editor, or admin"),
+):
+    """Create an API key."""
+    st, _, render_detail, _ = _out()
+    body = {"name": name, "scope": scope}
+    if description is not None:
+        body["description"] = description
+    if role is not None:
+        body["role"] = role
+    render_detail(_call("POST", json=body), use_json=st.use_json)
+
+
+@keys_app.command("get")
+def keys_get(key_id: int = typer.Argument(..., help="Key ID")):
+    """Get API key details."""
+    st, _, render_detail, _ = _out()
+    render_detail(_call("GET", f"/{key_id}"), use_json=st.use_json)
+
+
+@keys_app.command("update")
+def keys_update(
+    key_id: int = typer.Argument(..., help="Key ID"),
+    name: str = typer.Option(..., "--name", help="Key name"),
+    scope: Optional[str] = typer.Option(None, "--scope", help="Key scope: public or secret"),
+    description: Optional[str] = typer.Option(None, "--description", help="Key description"),
+    role: Optional[str] = typer.Option(None, "--role", help="Project role: support, editor, or admin"),
+):
+    """Update an API key."""
+    st, _, render_detail, _ = _out()
+    body = {"name": name}
+    if scope is not None:
+        body["scope"] = scope
+    if description is not None:
+        body["description"] = description
+    if role is not None:
+        body["role"] = role
+    render_detail(_call("PATCH", f"/{key_id}", json=body), use_json=st.use_json)
+
+
+@keys_app.command("delete")
+def keys_delete(key_id: int = typer.Argument(..., help="Key ID")):
+    """Delete (revoke) an API key."""
+    st, _, _, render_message = _out()
+    _call("DELETE", f"/{key_id}")
+    render_message(f"Key {key_id} deleted.", use_json=st.use_json)