ermes-cli 1.0.0__py3-none-any.whl

ermes_cli/commands/campaigns.py

@@ -0,0 +1,321 @@
+from __future__ import annotations
+import json as json_lib
+from datetime import datetime, timezone
+from typing import Optional
+import typer
+from ermes_cli.client import ErmesAPIError
+
+campaigns_app = typer.Typer(help="Manage campaigns", no_args_is_help=True)
+COLUMNS = ["id", "name", "type", "channel", "state", "send_at", "tags"]
+
+
+def _parse_send_at(value: str) -> str:
+    """Validate an ISO 8601 timestamp and normalize it to UTC.
+
+    Rejects tz-naive input: a naive timestamp interpreted in the wrong
+    zone mis-fires a blast, so the operator must state the offset.
+    """
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        typer.echo(
+            f"Invalid --send-at '{value}': expected ISO 8601, e.g. 2026-07-02T14:00:00-03:00",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+    if parsed.tzinfo is None:
+        typer.echo(
+            f"--send-at '{value}' must include a UTC offset, e.g. 2026-07-02T14:00:00-03:00 or 2026-07-02T17:00:00Z",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+    return parsed.astimezone(timezone.utc).isoformat()
+
+
+def _parse_id_list(value: str, option: str) -> list[int]:
+    try:
+        ids = [int(part) for part in value.split(",") if part.strip()]
+    except ValueError:
+        typer.echo(
+            f"Invalid {option} '{value}': expected comma-separated integers, e.g. 3,7",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+    if not ids:
+        typer.echo(
+            f"Invalid {option} '{value}': expected at least one integer ID", err=True
+        )
+        raise typer.Exit(code=1)
+    return ids
+
+
+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
+
+
+@campaigns_app.command("list")
+def campaigns_list(
+    status: Optional[str] = typer.Option(None, "--status", help="Filter by state"),
+    campaign_type: Optional[str] = typer.Option(None, "--type", help="Filter by type"),
+    limit: int = typer.Option(100, "--limit", help="Max results (0 = all)"),
+):
+    """List campaigns."""
+    client, st, render, _, _ = _get_deps()
+    params = {}
+    filter_obj = {}
+    if status:
+        filter_obj["state"] = status
+    if campaign_type:
+        filter_obj["type"] = campaign_type
+    if filter_obj:
+        params["filter"] = json_lib.dumps(filter_obj)
+    try:
+        data = client.get_paginated("/campaigns", 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)
+
+
+@campaigns_app.command("get")
+def campaigns_get(campaign_id: int = typer.Argument(..., help="Campaign ID")):
+    """Get campaign details."""
+    client, st, _, render_detail, _ = _get_deps()
+    try:
+        data = client.get(f"/campaigns/{campaign_id}")
+        render_detail(data, use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@campaigns_app.command("create")
+def campaigns_create(
+    campaign_type: str = typer.Option(..., "--type", help="blast or trigger"),
+    subscription: int = typer.Option(..., "--subscription", help="Subscription ID"),
+    provider: int = typer.Option(..., "--provider", help="Provider ID"),
+    name: Optional[str] = typer.Option(None, "--name", help="Campaign name"),
+    channel: Optional[str] = typer.Option(
+        None, "--channel", help="email|text|push|webhook"
+    ),
+    list_ids: Optional[str] = typer.Option(
+        None, "--list-ids", help="Comma-separated list IDs, e.g. 3,7"
+    ),
+    exclusion_list_ids: Optional[str] = typer.Option(
+        None, "--exclusion-list-ids", help="Comma-separated list IDs to exclude"
+    ),
+    send_at: Optional[str] = typer.Option(
+        None,
+        "--send-at",
+        help="ISO 8601 with UTC offset, e.g. 2026-07-02T14:00:00-03:00",
+    ),
+):
+    """Create a campaign."""
+    client, st, _, render_detail, _ = _get_deps()
+    body: dict = {
+        "type": campaign_type,
+        "subscription_id": subscription,
+        "provider_id": provider,
+    }
+    if name:
+        body["name"] = name
+    if channel:
+        body["channel"] = channel
+    if list_ids:
+        body["list_ids"] = _parse_id_list(list_ids, "--list-ids")
+    if exclusion_list_ids:
+        body["exclusion_list_ids"] = _parse_id_list(
+            exclusion_list_ids, "--exclusion-list-ids"
+        )
+    if send_at:
+        body["send_at"] = _parse_send_at(send_at)
+    try:
+        data = client.post("/campaigns", 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)
+
+
+@campaigns_app.command("update")
+def campaigns_update(
+    campaign_id: int = typer.Argument(..., help="Campaign ID"),
+    name: Optional[str] = typer.Option(None, "--name"),
+    status: Optional[str] = typer.Option(None, "--status"),
+    send_at: Optional[str] = typer.Option(
+        None,
+        "--send-at",
+        help="ISO 8601 with UTC offset, e.g. 2026-07-02T14:00:00-03:00",
+    ),
+    list_ids: Optional[str] = typer.Option(
+        None, "--list-ids", help="Comma-separated list IDs, e.g. 3,7"
+    ),
+    exclusion_list_ids: Optional[str] = typer.Option(
+        None, "--exclusion-list-ids", help="Comma-separated list IDs to exclude"
+    ),
+):
+    """Update a campaign."""
+    client, st, _, render_detail, _ = _get_deps()
+    body: dict = {}
+    if name:
+        body["name"] = name
+    if status:
+        body["state"] = status
+    if send_at:
+        body["send_at"] = _parse_send_at(send_at)
+    if list_ids:
+        body["list_ids"] = _parse_id_list(list_ids, "--list-ids")
+    if exclusion_list_ids:
+        body["exclusion_list_ids"] = _parse_id_list(
+            exclusion_list_ids, "--exclusion-list-ids"
+        )
+    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"/campaigns/{campaign_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)
+
+
+@campaigns_app.command("schedule")
+def campaigns_schedule(
+    campaign_id: int = typer.Argument(..., help="Campaign ID"),
+    send_at: str = typer.Option(
+        ...,
+        "--send-at",
+        help="ISO 8601 with UTC offset, e.g. 2026-07-02T14:00:00-03:00",
+    ),
+    list_ids: Optional[str] = typer.Option(
+        None, "--list-ids", help="Comma-separated list IDs, e.g. 3,7"
+    ),
+    exclusion_list_ids: Optional[str] = typer.Option(
+        None, "--exclusion-list-ids", help="Comma-separated list IDs to exclude"
+    ),
+):
+    """Schedule a campaign: set send_at and move it to state=scheduled."""
+    client, st, _, render_detail, _ = _get_deps()
+    body: dict = {"send_at": _parse_send_at(send_at), "state": "scheduled"}
+    if list_ids:
+        body["list_ids"] = _parse_id_list(list_ids, "--list-ids")
+    if exclusion_list_ids:
+        body["exclusion_list_ids"] = _parse_id_list(
+            exclusion_list_ids, "--exclusion-list-ids"
+        )
+    try:
+        data = client.patch(f"/campaigns/{campaign_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)
+
+
+@campaigns_app.command("delete")
+def campaigns_delete(campaign_id: int = typer.Argument(..., help="Campaign ID")):
+    """Delete (archive) a campaign."""
+    client, st, _, _, render_message = _get_deps()
+    try:
+        client.delete(f"/campaigns/{campaign_id}")
+        render_message(f"Campaign {campaign_id} deleted.", use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@campaigns_app.command("duplicate")
+def campaigns_duplicate(campaign_id: int = typer.Argument(..., help="Campaign ID")):
+    """Duplicate a campaign."""
+    client, st, _, render_detail, _ = _get_deps()
+    try:
+        data = client.post(f"/campaigns/{campaign_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)
+
+
+@campaigns_app.command("restore")
+def campaigns_restore(campaign_id: int = typer.Argument(..., help="Campaign ID")):
+    """Restore a deleted campaign."""
+    client, st, _, _, render_message = _get_deps()
+    try:
+        client.post(f"/campaigns/{campaign_id}/restore")
+        render_message(f"Campaign {campaign_id} restored.", use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@campaigns_app.command("preview")
+def campaigns_preview(campaign_id: int = typer.Argument(..., help="Campaign ID")):
+    """Preview campaign content."""
+    client, st, _, render_detail, _ = _get_deps()
+    try:
+        data = client.get(f"/campaigns/{campaign_id}/preview")
+        render_detail(data, use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@campaigns_app.command("users")
+def campaigns_users(
+    campaign_id: int = typer.Argument(..., help="Campaign ID"),
+    limit: int = typer.Option(100, "--limit"),
+):
+    """List users targeted by a campaign."""
+    client, st, render, _, _ = _get_deps()
+    try:
+        data = client.get_paginated(f"/campaigns/{campaign_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)
+
+
+@campaigns_app.command("trigger")
+def campaigns_trigger(
+    campaign_id: int = typer.Argument(..., help="Campaign ID"),
+    external_id: str = typer.Option(..., "--external-id", help="User external ID"),
+    event: str = typer.Option(..., "--event", help="Event data as JSON"),
+    email: Optional[str] = typer.Option(None, "--email", help="User email"),
+    phone: Optional[str] = typer.Option(None, "--phone", help="User phone"),
+    device_token: Optional[str] = typer.Option(
+        None, "--device-token", help="Push device token to register before the send"
+    ),
+    locale: Optional[str] = typer.Option(None, "--locale", help="User locale, e.g. pt-BR"),
+    tz: Optional[str] = typer.Option(
+        None, "--timezone", help="User timezone, e.g. America/Sao_Paulo"
+    ),
+):
+    """Trigger a campaign send for a user, identified by external ID."""
+    client, st, _, render_detail, _ = _get_deps()
+    try:
+        event_data = 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)
+    user = {"external_id": external_id}
+    for key, value in (
+        ("email", email),
+        ("phone", phone),
+        ("device_token", device_token),
+        ("locale", locale),
+        ("timezone", tz),
+    ):
+        if value is not None:
+            user[key] = value
+    try:
+        data = client.post(
+            f"/campaigns/{campaign_id}/trigger",
+            json={"user": user, "event": event_data},
+        )
+        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/config_cmd.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+from typing import Optional
+import typer
+from ermes_cli.config import (
+    add_profile,
+    remove_profile,
+    set_default_profile,
+    list_profiles,
+    ConfigError,
+    DEFAULT_BASE_URL,
+)
+from ermes_cli.output import render, render_message
+
+config_app = typer.Typer(help="Manage connection profiles", no_args_is_help=True)
+
+
+@config_app.command("init")
+def config_init(
+    name: str = typer.Option(..., prompt="Profile name"),
+    api_key: str = typer.Option(..., prompt="API key (sk_...)"),
+    base_url: str = typer.Option(
+        DEFAULT_BASE_URL, prompt="Base URL", show_default=True
+    ),
+):
+    """[Legacy] Single-project profile setup.
+
+    Prefer `ermes login` — runs an Auth0 device flow, auto-discovers every
+    project you have access to, and auto-creates per-project sk_ keys. One
+    auth event unlocks everything; this command requires a manual paste per
+    project.
+    """
+    from ermes_cli.main import state
+
+    typer.secho(
+        "DEPRECATED: `ermes config init` is single-project + manual. "
+        "Use `ermes login` for Auth0-based multi-project auto-discovery.",
+        fg=typer.colors.YELLOW,
+        err=True,
+    )
+
+    try:
+        add_profile(name, api_key, base_url)
+        render_message(f"Profile '{name}' created.", use_json=state.use_json)
+    except ConfigError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@config_app.command("list")
+def config_list():
+    """Show all configured profiles."""
+    from ermes_cli.main import state
+
+    profiles = list_profiles()
+    render(
+        profiles,
+        columns=["name", "base_url", "api_key", "is_default"],
+        use_json=state.use_json,
+        title="Profiles",
+    )
+
+
+@config_app.command("add")
+def config_add(
+    name: str = typer.Argument(..., help="Profile name"),
+    api_key: str = typer.Option(..., "--api-key", help="API key (sk_...)"),
+    base_url: str = typer.Option(
+        DEFAULT_BASE_URL, "--base-url", help="API base URL"
+    ),
+):
+    """Add a new profile."""
+    from ermes_cli.main import state
+
+    try:
+        add_profile(name, api_key, base_url)
+        render_message(f"Profile '{name}' added.", use_json=state.use_json)
+    except ConfigError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@config_app.command("remove")
+def config_remove(name: str = typer.Argument(..., help="Profile name")):
+    """Remove a profile."""
+    from ermes_cli.main import state
+
+    try:
+        remove_profile(name)
+        render_message(f"Profile '{name}' removed.", use_json=state.use_json)
+    except ConfigError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@config_app.command("set-default")
+def config_set_default(name: str = typer.Argument(..., help="Profile name")):
+    """Set the default profile."""
+    from ermes_cli.main import state
+
+    try:
+        set_default_profile(name)
+        render_message(f"Default profile set to '{name}'.", use_json=state.use_json)
+    except ConfigError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)

ermes_cli/commands/data_paths.py

@@ -0,0 +1,103 @@
+"""`ermes data-paths` — read the platform's schema introspection.
+
+Output of /api/client/data/paths:
+    {
+      "userPaths":  ["$.name", "$.email", ...],          # flat list of JSON paths
+      "eventPaths": {"signup": ["$.utm_source", ...],    # keyed by event name
+                     "purchase": [...]}
+    }
+
+We flatten that into `{type, name, path}` rows where:
+    type=user                                   → name="" (user paths have no event)
+    type=event, name=signup, path=$.utm_source
+"""
+
+from __future__ import annotations
+
+import typer
+
+from ermes_cli.client import ErmesAPIError
+
+data_paths_app = typer.Typer(help="Manage data paths", no_args_is_help=True)
+COLUMNS = ["type", "name", "path"]
+
+
+def _get_deps():
+    from ermes_cli.main import get_client, state
+    from ermes_cli.output import render, render_message
+
+    return get_client(), state, render, render_message
+
+
+def _flatten_paths(data: dict) -> list[dict]:
+    """Normalize /data/paths response into a flat row list.
+
+    Handles three shapes for forward-compatibility:
+      1. {userPaths: [str], eventPaths: {name: [str]}}   ← current platform
+      2. {user: [str], event: {name: [str]}}             ← short-key variant
+      3. {user: [{path, name}], event: [{path, name}]}   ← hypothetical dict-row variant
+    """
+    rows: list[dict] = []
+
+    for user_key in ("userPaths", "user"):
+        user_paths = data.get(user_key)
+        if isinstance(user_paths, list):
+            for entry in user_paths:
+                if isinstance(entry, str):
+                    rows.append({"type": "user", "name": "", "path": entry})
+                elif isinstance(entry, dict):
+                    rows.append({"type": "user", "name": entry.get("name", ""),
+                                 "path": entry.get("path", "")})
+            break
+
+    for event_key in ("eventPaths", "event"):
+        event_paths = data.get(event_key)
+        if isinstance(event_paths, dict):
+            for event_name, paths in sorted(event_paths.items()):
+                if not isinstance(paths, list):
+                    continue
+                for entry in paths:
+                    if isinstance(entry, str):
+                        rows.append({"type": "event", "name": event_name, "path": entry})
+                    elif isinstance(entry, dict):
+                        rows.append({
+                            "type": "event",
+                            "name": entry.get("name", event_name),
+                            "path": entry.get("path", ""),
+                        })
+            break
+        if isinstance(event_paths, list):
+            for entry in event_paths:
+                if isinstance(entry, str):
+                    rows.append({"type": "event", "name": "", "path": entry})
+                elif isinstance(entry, dict):
+                    rows.append({"type": "event", "name": entry.get("name", ""),
+                                 "path": entry.get("path", "")})
+            break
+
+    return rows
+
+
+@data_paths_app.command("list")
+def data_paths_list():
+    """List known user/event data field paths."""
+    client, st, render, _ = _get_deps()
+    try:
+        data = client.get("/data/paths")
+        rows = _flatten_paths(data) if isinstance(data, dict) else []
+        render(rows, columns=COLUMNS, use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@data_paths_app.command("sync")
+def data_paths_sync():
+    """Trigger a re-sync of data paths from recent users + events."""
+    client, st, _, render_message = _get_deps()
+    try:
+        client.post("/data/paths/sync")
+        render_message("Data paths sync triggered.", use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)