ermes-cli 1.0.0__py3-none-any.whl

ermes_cli/commands/projects.py

@@ -0,0 +1,286 @@
+"""`ermes projects` / `ermes use` — manage the projects.yml cache."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Optional
+from zoneinfo import available_timezones
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from ermes_cli import write_mode
+from ermes_cli.config import (
+    ConfigError,
+    get_active_project_id,
+    get_auth0_email,
+    get_projects,
+    mask_key,
+    set_active_project_id,
+)
+from ermes_cli.errors import WriteBlockedError
+
+if TYPE_CHECKING:
+    from ermes_cli import admin_api
+
+console = Console()
+
+# BCP-47 language tag: 2-3 letter primary subtag + optional alnum subtags.
+# Deliberately permissive — the server's Intl.DisplayNames is the real
+# authority. This only catches the common `en_US` (underscore) footgun and
+# obviously-malformed input before it reaches the API and 500s.
+_LOCALE_RE = re.compile(r"^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$")
+
+
+def _validate_locale(locale: str) -> None:
+    """Reject malformed locales client-side (a bad tag 500s server-side)."""
+    if not _LOCALE_RE.match(locale):
+        console.print(
+            f"[red]Invalid --locale {locale!r}.[/red] Use a BCP-47 tag like "
+            "`en`, `pt-BR`, or `pl-PL` (hyphen, not underscore)."
+        )
+        raise typer.Exit(code=1)
+
+
+def _validate_timezone(timezone: str) -> None:
+    """Reject non-IANA timezones client-side (the server stores them unchecked)."""
+    if timezone not in available_timezones():
+        console.print(
+            f"[red]Invalid --timezone {timezone!r}.[/red] Use an IANA name like "
+            "`America/Sao_Paulo` or `UTC`."
+        )
+        raise typer.Exit(code=1)
+
+
+projects_app = typer.Typer(help="Manage cached Ermes projects", no_args_is_help=True)
+
+
+@projects_app.command("refresh")
+def projects_refresh(
+    base_url: str = typer.Option(
+        None,
+        "--base-url",
+        help="Override the API base URL (defaults to projects.yml's value).",
+    ),
+) -> None:
+    """Re-sync projects.yml from the Ermes API. Auto-refreshes Auth0 token if expired."""
+    from ermes_cli.commands.auth_cmds import refresh_projects as _refresh
+
+    _refresh(base_url=base_url)
+
+
+def _run_create_project(
+    api_base: str,
+    result: admin_api.ExchangeResult,
+    name: str,
+    timezone: str,
+    locale: str,
+    description: str | None,
+    activate: bool,
+) -> None:
+    """Core logic for `projects create`: call the API, re-sync, write projects.yml."""
+    from ermes_cli import admin_api
+    from ermes_cli.commands.auth_cmds import _bootstrap_projects, _hostname, _write_projects_file
+
+    try:
+        new_project = admin_api.create_project(
+            api_base,
+            result.ermes_access_token,
+            name=name,
+            timezone=timezone,
+            locale=locale,
+            description=description,
+        )
+    except admin_api.AdminAPIError as exc:
+        console.print(f"[red]Project creation failed:[/red] {exc}")
+        raise typer.Exit(code=1)
+
+    console.print(
+        f"[green]+[/green] Created project [bold]{new_project.name}[/bold] "
+        f"(id={new_project.id})."
+    )
+    console.print("[bold]Re-syncing projects + minting CLI key…[/bold]")
+
+    try:
+        projects, keys = _bootstrap_projects(api_base, result.ermes_access_token, result.admin_email)
+    except admin_api.AdminAPIError as exc:
+        console.print(f"[red]Project discovery failed:[/red] {exc}")
+        raise typer.Exit(code=1)
+
+    # Key provisioning is best-effort. If it fails for the project we just
+    # created, DON'T set it active — a keyless active project makes the next
+    # `ermes <cmd>` fail with a confusing auth error. Cache what we have, tell
+    # the user to refresh, and exit non-zero so scripts notice.
+    new_key = None
+    try:
+        new_key = admin_api.create_cli_key(
+            api_base, result.ermes_access_token, new_project.id, _hostname()
+        )
+        keys[new_project.id] = new_key
+    except admin_api.AdminAPIError as exc:
+        console.print(f"[yellow]![/yellow] Key provisioning failed: {exc}")
+    if new_key is None or not new_key.value:
+        _write_projects_file(
+            base_url=api_base,
+            auth0_email=result.admin_email,
+            organization_id=result.organization_id,
+            projects=projects,
+            keys=keys,
+            active_project_id=get_active_project_id(),  # keep prior active (may be None)
+        )
+        console.print(
+            f"[yellow]![/yellow] Project [bold]{new_project.name}[/bold] "
+            f"(id={new_project.id}) was created, but minting its CLI key failed. "
+            f"Run `ermes projects refresh`, then `ermes use {new_project.id}`."
+        )
+        raise typer.Exit(code=1)
+
+    # Default: make the new project active. With --no-activate keep the current
+    # active project, but fall back to the new one if nothing is active yet.
+    active_id = new_project.id if activate else get_active_project_id()
+    if active_id not in {p.id for p in projects}:
+        active_id = new_project.id
+
+    _write_projects_file(
+        base_url=api_base,
+        auth0_email=result.admin_email,
+        organization_id=result.organization_id,
+        projects=projects,
+        keys=keys,
+        active_project_id=active_id,
+    )
+    suffix = " Now active." if active_id == new_project.id else ""
+    console.print(
+        f"[green]✓[/green] Project [bold]{new_project.name}[/bold] "
+        f"(id={new_project.id}) cached.{suffix}"
+    )
+
+
+@projects_app.command("create")
+def projects_create(
+    name: str = typer.Option(
+        ..., "--name", help="Project name (shown in the UI + CLI)."
+    ),
+    timezone: str = typer.Option(
+        ..., "--timezone", help="IANA timezone, e.g. America/Sao_Paulo."
+    ),
+    locale: str = typer.Option(
+        ..., "--locale", help="BCP 47 locale, e.g. pt-BR or en."
+    ),
+    description: Optional[str] = typer.Option(
+        None, "--description", help="Optional project description."
+    ),
+    activate: bool = typer.Option(
+        True,
+        "--activate/--no-activate",
+        help="Switch the active project to the new one (default). With "
+        "--no-activate the current active project is kept, unless none is set.",
+    ),
+    base_url: Optional[str] = typer.Option(
+        None,
+        "--base-url",
+        help="Override the API base URL (defaults to projects.yml's value).",
+    ),
+) -> None:
+    """Create a new Ermes project in your organization, then cache it + mint a CLI key.
+
+    Requires `ermes login` (uses your Auth0 session → Ermes admin JWT) and org
+    role `admin` or `owner`. After creating the project server-side, projects.yml
+    is re-synced and a per-admin `sk_` key is minted for the new project,
+    ready for `ermes campaigns list` etc.
+    """
+    from ermes_cli.commands.auth_cmds import _ensure_admin_session
+
+    # Validate input before spending a network round-trip on auth.
+    _validate_locale(locale)
+    _validate_timezone(timezone)
+
+    # Creating a project is a write. The admin_api path bypasses client.py's
+    # guard, so enforce it here to stay consistent with `campaigns create` etc.
+    try:
+        write_mode.assert_writes_allowed("POST", "/api/admin/projects")
+    except WriteBlockedError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(code=1)
+
+    api_base, result = _ensure_admin_session(base_url)
+    _run_create_project(api_base, result, name, timezone, locale, description, activate)
+
+
+@projects_app.command("list")
+def projects_list() -> None:
+    """Show all projects cached in ~/.ermes/projects.yml."""
+    projects = get_projects()
+    if not projects:
+        console.print(
+            "[yellow]No cached projects.[/yellow] Run `ermes login` to discover them."
+        )
+        raise typer.Exit(code=0)
+
+    active = get_active_project_id()
+    email = get_auth0_email()
+
+    table = Table(title=f"Projects ({email or 'unknown user'})")
+    table.add_column("ID", justify="right")
+    table.add_column("Name")
+    table.add_column("Role")
+    table.add_column("Key", overflow="fold")
+    table.add_column("Active")
+    for pid in sorted(projects.keys()):
+        p = projects[pid]
+        key = p.get("api_key") or ""
+        key_str = mask_key(key) if key else "[dim](no key)[/dim]"
+        table.add_row(
+            str(pid),
+            str(p.get("name", "")),
+            str(p.get("role", "")),
+            key_str,
+            "★" if pid == active else "",
+        )
+    console.print(table)
+
+
+def use(
+    name_or_id: str = typer.Argument(
+        ..., help="Project name or numeric id (from `ermes projects list`)"
+    ),
+) -> None:
+    """Switch the active project. Affects every subsequent CLI + MCP call."""
+    projects = get_projects()
+    if not projects:
+        console.print("[yellow]No cached projects.[/yellow] Run `ermes login` first.")
+        raise typer.Exit(code=1)
+
+    target_id: int | None = None
+    if name_or_id.isdigit():
+        candidate = int(name_or_id)
+        if candidate in projects:
+            target_id = candidate
+    if target_id is None:
+        for pid, proj in projects.items():
+            if str(proj.get("name", "")).lower() == name_or_id.lower():
+                target_id = pid
+                break
+
+    if target_id is None:
+        console.print(
+            f"[red]No project matching {name_or_id!r}[/red] in projects.yml. "
+            "Run `ermes projects list` to see what's cached."
+        )
+        raise typer.Exit(code=1)
+
+    from ermes_cli.commands.auth_cmds import ensure_project_key
+
+    try:
+        set_active_project_id(target_id)
+        ensure_project_key(target_id)
+    except ConfigError as exc:
+        console.print(f"[red]{exc}[/red]")
+        raise typer.Exit(code=1)
+
+    proj = projects[target_id]
+    console.print(
+        f"[green]✓[/green] Active project: [bold]{proj.get('name')}[/bold] "
+        f"(id={target_id})"
+    )

ermes_cli/commands/providers.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+import json as json_lib
+from typing import Optional
+
+import typer
+from ermes_cli.client import ErmesAPIError
+
+providers_app = typer.Typer(help="Manage providers", no_args_is_help=True)
+COLUMNS = ["id", "name", "group", "type", "is_default"]
+
+
+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
+
+
+@providers_app.command("list")
+def providers_list(
+    limit: int = typer.Option(100, "--limit", help="Max results (0 = all)"),
+):
+    """List providers."""
+    client, st, render, _, _ = _get_deps()
+    try:
+        data = client.get_paginated("/providers", 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)
+
+
+@providers_app.command("all")
+def providers_all():
+    """List all providers without pagination."""
+    client, st, render, _, _ = _get_deps()
+    try:
+        data = client.get("/providers/all")
+        render(data, columns=COLUMNS, use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@providers_app.command("meta")
+def providers_meta():
+    """List available provider types."""
+    client, st, _, render_detail, _ = _get_deps()
+    try:
+        data = client.get("/providers/meta")
+        if st.use_json:
+            import json
+
+            print(json.dumps(data, indent=2))
+        else:
+            render_detail(data, use_json=False)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+def _provider_body(
+    data: str,
+    name: Optional[str],
+    is_default: Optional[bool],
+    rate_limit: Optional[float],
+    rate_interval: Optional[str],
+) -> dict:
+    try:
+        body = {"data": json_lib.loads(data)}
+    except json_lib.JSONDecodeError as e:
+        typer.echo(f"Invalid JSON for --data: {e}", err=True)
+        raise typer.Exit(code=1)
+    if name is not None:
+        body["name"] = name
+    if is_default is not None:
+        body["is_default"] = is_default
+    if rate_limit is not None:
+        body["rate_limit"] = rate_limit
+    if rate_interval is not None:
+        body["rate_interval"] = rate_interval
+    return body
+
+
+@providers_app.command("create")
+def providers_create(
+    group: str = typer.Option(
+        ..., "--group", help="Provider group: email, text, push, webhook, analytics"
+    ),
+    provider_type: str = typer.Option(..., "--type", help="Provider type"),
+    data: str = typer.Option(..., "--data", help="Provider-specific data JSON"),
+    name: Optional[str] = typer.Option(None, "--name", help="Provider name"),
+    is_default: Optional[bool] = typer.Option(
+        None, "--is-default", help="Set as default provider"
+    ),
+    rate_limit: Optional[float] = typer.Option(
+        None, "--rate-limit", help="Per-interval send limit"
+    ),
+    rate_interval: Optional[str] = typer.Option(
+        None, "--rate-interval", help="second, minute, hour, or day"
+    ),
+):
+    """Create a provider."""
+    client, st, _, render_detail, _ = _get_deps()
+    body = _provider_body(data, name, is_default, rate_limit, rate_interval)
+    try:
+        result = client.post(f"/providers/{group}/{provider_type}", json=body)
+        render_detail(result, use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@providers_app.command("get")
+def providers_get(provider_id: int = typer.Argument(..., help="Provider ID")):
+    """Get provider details (fetches list first to resolve group/type)."""
+    client, st, _, render_detail, _ = _get_deps()
+    try:
+        providers = client.get_paginated("/providers", limit=0)
+        provider = None
+        for p in providers:
+            if p.get("id") == provider_id:
+                provider = p
+                break
+        if not provider:
+            typer.echo(f"Provider {provider_id} not found.", err=True)
+            raise typer.Exit(code=1)
+        data = client.get(
+            f"/providers/{provider['group']}/{provider['type']}/{provider_id}"
+        )
+        render_detail(data, use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@providers_app.command("update")
+def providers_update(
+    provider_id: int = typer.Argument(..., help="Provider ID"),
+    group: str = typer.Option(..., "--group", help="Provider group"),
+    provider_type: str = typer.Option(..., "--type", help="Provider type"),
+    data: str = typer.Option(
+        ..., "--data", help="Provider-specific data JSON (replaces the full config)"
+    ),
+    name: Optional[str] = typer.Option(None, "--name", help="Provider name"),
+    is_default: Optional[bool] = typer.Option(
+        None, "--is-default", help="Set as default provider"
+    ),
+    rate_limit: Optional[float] = typer.Option(
+        None, "--rate-limit", help="Per-interval send limit"
+    ),
+    rate_interval: Optional[str] = typer.Option(
+        None, "--rate-interval", help="second, minute, hour, or day"
+    ),
+):
+    """Update a provider."""
+    client, st, _, render_detail, render_message = _get_deps()
+    body = _provider_body(data, name, is_default, rate_limit, rate_interval)
+    try:
+        result = client.patch(
+            f"/providers/{group}/{provider_type}/{provider_id}", json=body
+        )
+        # The provider PATCH endpoint returns an empty body ({}), which would
+        # render as an empty table. Fall back to a confirmation message so the
+        # user gets feedback; still render the object if the API ever returns one.
+        if result:
+            render_detail(result, use_json=st.use_json)
+        else:
+            render_message(f"Provider {provider_id} updated.", use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@providers_app.command("delete")
+def providers_delete(provider_id: int = typer.Argument(..., help="Provider ID")):
+    """Delete a provider."""
+    client, st, _, _, render_message = _get_deps()
+    try:
+        client.delete(f"/providers/{provider_id}")
+        render_message(f"Provider {provider_id} deleted.", use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)

ermes_cli/commands/subscriptions.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+from typing import Optional
+import typer
+from ermes_cli.client import ErmesAPIError
+
+subscriptions_app = typer.Typer(help="Manage subscriptions", no_args_is_help=True)
+COLUMNS = ["id", "name", "channel"]
+
+
+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
+
+
+@subscriptions_app.command("list")
+def subscriptions_list(
+    limit: int = typer.Option(100, "--limit", help="Max results (0 = all)"),
+):
+    """List subscriptions."""
+    client, st, render, _, _ = _get_deps()
+    try:
+        data = client.get_paginated("/subscriptions", 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)
+
+
+@subscriptions_app.command("get")
+def subscriptions_get(subscription_id: int = typer.Argument(..., help="Subscription ID")):
+    """Get subscription details."""
+    client, st, _, render_detail, _ = _get_deps()
+    try:
+        data = client.get(f"/subscriptions/{subscription_id}")
+        render_detail(data, use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@subscriptions_app.command("create")
+def subscriptions_create(
+    name: str = typer.Option(..., "--name", help="Subscription name"),
+    channel: str = typer.Option(..., "--channel", help="Channel (email, text, push, webhook)"),
+):
+    """Create a subscription."""
+    client, st, _, render_detail, _ = _get_deps()
+    try:
+        data = client.post("/subscriptions", json={"name": name, "channel": channel})
+        render_detail(data, use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@subscriptions_app.command("update")
+def subscriptions_update(
+    subscription_id: int = typer.Argument(..., help="Subscription ID"),
+    name: Optional[str] = typer.Option(None, "--name"),
+):
+    """Update a subscription."""
+    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"/subscriptions/{subscription_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)

ermes_cli/commands/tags.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+from typing import Optional
+import typer
+from ermes_cli.client import ErmesAPIError
+
+tags_app = typer.Typer(help="Manage tags", no_args_is_help=True)
+COLUMNS = ["id", "name"]
+
+
+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
+
+
+@tags_app.command("list")
+def tags_list(
+    limit: int = typer.Option(100, "--limit", help="Max results (0 = all)"),
+):
+    """List tags."""
+    client, st, render, _, _ = _get_deps()
+    try:
+        data = client.get_paginated("/tags", 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)
+
+
+@tags_app.command("get")
+def tags_get(tag_id: int = typer.Argument(..., help="Tag ID")):
+    """Get tag details."""
+    client, st, _, render_detail, _ = _get_deps()
+    try:
+        data = client.get(f"/tags/{tag_id}")
+        render_detail(data, use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@tags_app.command("create")
+def tags_create(
+    name: str = typer.Option(..., "--name", help="Tag name"),
+):
+    """Create a tag."""
+    client, st, _, render_detail, _ = _get_deps()
+    try:
+        data = client.post("/tags", json={"name": name})
+        render_detail(data, use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+
+
+@tags_app.command("update")
+def tags_update(
+    tag_id: int = typer.Argument(..., help="Tag ID"),
+    name: Optional[str] = typer.Option(None, "--name"),
+):
+    """Update a tag."""
+    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"/tags/{tag_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)
+
+
+@tags_app.command("delete")
+def tags_delete(tag_id: int = typer.Argument(..., help="Tag ID")):
+    """Delete a tag."""
+    client, st, _, _, render_message = _get_deps()
+    try:
+        client.delete(f"/tags/{tag_id}")
+        render_message(f"Tag {tag_id} deleted.", use_json=st.use_json)
+    except ErmesAPIError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)