commune-cli 0.1.0__py3-none-any.whl

commune_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Commune CLI — official command-line interface for the Commune email API."""
+
+__version__ = "0.1.0"

commune_cli/client.py

@@ -0,0 +1,111 @@
+"""CommuneClient — thin httpx wrapper with API key auth.
+
+Auth: Authorization: Bearer comm_...
+
+Raises:
+  httpx.ConnectError / httpx.TimeoutException — caller wraps with network_error()
+  All non-2xx responses — caller checks response.is_success and calls api_error()
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+from .state import AppState
+
+DEFAULT_TIMEOUT = 30.0
+
+
+class CommuneClient:
+    """HTTP client for the Commune API.
+
+    Usage:
+        client = CommuneClient.from_state(state)
+        r = client.get("/v1/domains")
+        if not r.is_success:
+            api_error(r, json_output=state.should_json())
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+
+    @classmethod
+    def from_state(cls, state: AppState) -> "CommuneClient":
+        return cls(
+            base_url=state.base_url,
+            api_key=state.api_key,
+            timeout=DEFAULT_TIMEOUT,
+        )
+
+    def _base_headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {
+            "Content-Type": "application/json",
+            "User-Agent": "commune-cli/0.1.0",
+        }
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def _url(self, path: str) -> str:
+        return self.base_url + path
+
+    def _req(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[dict[str, Any]] = None,
+        json: Optional[Any] = None,
+        data: Optional[bytes] = None,
+        extra_headers: Optional[dict[str, str]] = None,
+    ) -> httpx.Response:
+        headers = self._base_headers()
+        if extra_headers:
+            headers.update(extra_headers)
+        if data is not None:
+            headers.pop("Content-Type", None)
+
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        with httpx.Client(timeout=self.timeout) as client:
+            return client.request(
+                method,
+                self._url(path),
+                headers=headers,
+                params=params or None,
+                json=json,
+                content=data,
+            )
+
+    def get(self, path: str, *, params: Optional[dict[str, Any]] = None) -> httpx.Response:
+        return self._req("GET", path, params=params)
+
+    def post(
+        self,
+        path: str,
+        *,
+        json: Optional[Any] = None,
+        data: Optional[bytes] = None,
+        extra_headers: Optional[dict[str, str]] = None,
+        params: Optional[dict[str, Any]] = None,
+    ) -> httpx.Response:
+        return self._req("POST", path, json=json, data=data, extra_headers=extra_headers, params=params)
+
+    def patch(self, path: str, *, json: Optional[Any] = None) -> httpx.Response:
+        return self._req("PATCH", path, json=json)
+
+    def delete(self, path: str, *, params: Optional[dict[str, Any]] = None) -> httpx.Response:
+        return self._req("DELETE", path, params=params)
+
+    def put(self, path: str, *, json: Optional[Any] = None) -> httpx.Response:
+        return self._req("PUT", path, json=json)

commune_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Command modules for the Commune CLI."""

commune_cli/commands/attachments.py

@@ -0,0 +1,127 @@
+"""commune attachments — upload files and get download URLs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from ..client import CommuneClient
+from ..errors import api_error, auth_required_error, network_error, validation_error
+from ..output import print_json, print_record, print_success
+from ..state import AppState
+
+app = typer.Typer(help="Attachment management.", no_args_is_help=True)
+
+
+@app.command("upload")
+def attachments_upload(
+    ctx: typer.Context,
+    file: Path = typer.Argument(..., help="Path to the file to upload.", exists=True, readable=True),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Upload a file as an attachment. POST /v1/attachments/upload.
+
+    Returns an attachment ID that can be referenced when sending emails.
+    """
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    file_path = Path(file)
+    if not file_path.is_file():
+        validation_error(f"File not found: {file}", json_output=json_output or state.should_json())
+
+    import mimetypes
+    mime_type, _ = mimetypes.guess_type(str(file_path))
+    if not mime_type:
+        mime_type = "application/octet-stream"
+
+    file_data = file_path.read_bytes()
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.post(
+            "/v1/attachments/upload",
+            data=file_data,
+            extra_headers={
+                "Content-Type": mime_type,
+                "X-Filename": file_path.name,
+            },
+        )
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    data = r.json()
+    if json_output or state.should_json():
+        print_json(data)
+        return
+
+    att_id = data.get("id") or data.get("attachmentId", "")
+    print_success(f"Uploaded [bold]{file_path.name}[/bold]. Attachment ID: [cyan]{att_id}[/cyan]")
+
+
+@app.command("get")
+def attachments_get(
+    ctx: typer.Context,
+    attachment_id: str = typer.Argument(..., help="Attachment ID."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Get attachment metadata. GET /v1/attachments/{attachmentId}."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.get(f"/v1/attachments/{attachment_id}")
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    print_record(r.json(), json_output=json_output or state.should_json(), title="Attachment")
+
+
+@app.command("url")
+def attachments_url(
+    ctx: typer.Context,
+    attachment_id: str = typer.Argument(..., help="Attachment ID."),
+    expires_in: Optional[int] = typer.Option(
+        None,
+        "--expires-in",
+        help="URL expiry in seconds. Default: 3600.",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Get a presigned download URL for an attachment. GET /v1/attachments/{attachmentId}/url."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    client = CommuneClient.from_state(state)
+    params: dict = {}
+    if expires_in is not None:
+        params["expiresIn"] = expires_in
+
+    try:
+        r = client.get(f"/v1/attachments/{attachment_id}/url", params=params or None)
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    data = r.json()
+    if json_output or state.should_json():
+        print_json(data)
+        return
+
+    url = data.get("url", "")
+    from ..output import print_value
+    print_value(url, json_output=False, key="url")

commune_cli/commands/config_cmd.py

@@ -0,0 +1,89 @@
+"""commune config — manage ~/.commune/config.toml."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from ..config import KNOWN_KEYS, config_path, delete_value, get_value, load_config, mask, set_value
+from ..output import print_kv, print_success, print_value, print_warning
+
+app = typer.Typer(help="Manage CLI configuration.", no_args_is_help=True)
+
+
+@app.command("set")
+def config_set(
+    key: str = typer.Argument(..., help=f"Config key. Known keys: {', '.join(KNOWN_KEYS)}."),
+    value: str = typer.Argument(..., help="Value to store."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Set a config key and persist to ~/.commune/config.toml."""
+    if key not in KNOWN_KEYS:
+        known = ", ".join(KNOWN_KEYS)
+        print_warning(f"Unknown key '{key}'. Known keys: {known}")
+    set_value(key, value)
+    display = mask(value) if key == "api_key" else value
+    print_success(f"Set {key} = {display}  ({config_path()})")
+    if json_output:
+        from ..output import print_json
+        print_json({"key": key, "set": True})
+
+
+@app.command("get")
+def config_get(
+    key: str = typer.Argument(..., help="Config key to retrieve."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Get a single config value."""
+    value = get_value(key)
+    if value is None:
+        print_warning(f"Key '{key}' is not set in config.")
+        raise typer.Exit(1)
+    # Mask api_key in terminal display
+    display = mask(value) if key == "api_key" else value
+    print_value(display, json_output=json_output, key=key)
+
+
+@app.command("show")
+def config_show(
+    reveal: bool = typer.Option(False, "--reveal", help="Show full api_key (not masked)."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Print all config values. Masks api_key unless --reveal is passed."""
+    cfg = load_config()
+    if not cfg:
+        print_warning(f"No config file found at {config_path()}")
+        raise typer.Exit(0)
+
+    pairs: dict[str, str] = {}
+    for k, v in cfg.items():
+        if k == "api_key" and not reveal:
+            pairs[k] = mask(v)
+        else:
+            pairs[k] = str(v)
+
+    print_kv(pairs, json_output=json_output, title=f"Config  {config_path()}")
+
+
+@app.command("unset")
+def config_unset(
+    key: str = typer.Argument(..., help="Config key to remove."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Remove a key from config."""
+    removed = delete_value(key)
+    if removed:
+        print_success(f"Removed '{key}' from config.")
+    else:
+        print_warning(f"Key '{key}' was not set.")
+    if json_output:
+        from ..output import print_json
+        print_json({"key": key, "removed": removed})
+
+
+@app.command("path")
+def config_path_cmd() -> None:
+    """Print the path to the config file."""
+    import sys
+    sys.stdout.write(str(config_path()) + "\n")

commune_cli/commands/data.py

@@ -0,0 +1,130 @@
+"""commune data — data deletion requests (GDPR / destructive).
+
+These commands are destructive and irreversible. They require explicit confirmation.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from ..client import CommuneClient
+from ..errors import api_error, auth_required_error, network_error
+from ..output import print_json, print_record, print_success, print_warning, print_status
+from ..state import AppState
+
+app = typer.Typer(
+    help="Data deletion requests. Destructive — use with care.",
+    no_args_is_help=True,
+)
+
+
+@app.command("delete-request")
+def data_delete_request(
+    ctx: typer.Context,
+    email: Optional[str] = typer.Option(None, "--email", help="Email address to delete data for."),
+    inbox_id: Optional[str] = typer.Option(None, "--inbox-id", help="Inbox ID scope for deletion."),
+    domain_id: Optional[str] = typer.Option(None, "--domain-id", help="Domain ID scope for deletion."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Initiate a data deletion request. POST /v1/data/deletion-request.
+
+    Returns a preview of what will be deleted and a confirmation token.
+    Use `commune data delete-confirm <id>` to execute.
+    """
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    body: dict = {}
+    if email:
+        body["email"] = email
+    if inbox_id:
+        body["inboxId"] = inbox_id
+    if domain_id:
+        body["domainId"] = domain_id
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.post("/v1/data/deletion-request", json=body)
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    data = r.json()
+    if json_output or state.should_json():
+        print_json(data)
+        return
+
+    req_id = data.get("id", "")
+    print_warning(f"Deletion request created. ID: [bold]{req_id}[/bold]")
+    print_status("Review the preview above, then confirm with:")
+    print_status(f"  commune data delete-confirm {req_id}")
+
+
+@app.command("delete-confirm")
+def data_delete_confirm(
+    ctx: typer.Context,
+    request_id: str = typer.Argument(..., help="Deletion request ID from `commune data delete-request`."),
+    confirm: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt. REQUIRED for non-interactive use."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Confirm and execute a data deletion request. POST /v1/data/deletion-request/{id}/confirm.
+
+    This action is IRREVERSIBLE. Data is permanently deleted.
+    """
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    if not confirm:
+        if state.is_tty():
+            print_warning("[bold red]WARNING:[/bold red] This action permanently deletes data and cannot be undone.")
+            typer.confirm(f"Confirm deletion of request {request_id}?", abort=True)
+        else:
+            # Non-TTY without --yes flag: require explicit confirmation
+            from ..errors import validation_error
+            validation_error(
+                "Deletion requires --yes flag in non-interactive mode.",
+                json_output=json_output or state.should_json(),
+            )
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.post(f"/v1/data/deletion-request/{request_id}/confirm")
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    if json_output or state.should_json():
+        print_json(r.json())
+        return
+    print_success(f"Deletion confirmed. Request [bold]{request_id}[/bold] is processing.")
+
+
+@app.command("delete-status")
+def data_delete_status(
+    ctx: typer.Context,
+    request_id: str = typer.Argument(..., help="Deletion request ID."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Get the status of a data deletion request. GET /v1/data/deletion-request/{id}."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.get(f"/v1/data/deletion-request/{request_id}")
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    print_record(r.json(), json_output=json_output or state.should_json(), title=f"Deletion Request {request_id}")

commune_cli/commands/delivery.py

@@ -0,0 +1,126 @@
+"""commune delivery — delivery metrics, events, and suppressions."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from ..client import CommuneClient
+from ..errors import api_error, auth_required_error, network_error
+from ..output import print_list, print_record
+from ..state import AppState
+
+app = typer.Typer(help="Delivery metrics, events, and suppressions.", no_args_is_help=True)
+
+PERIOD_HELP = "Time period: 1d, 7d, 30d (default: 7d)."
+
+
+@app.command("metrics")
+def delivery_metrics(
+    ctx: typer.Context,
+    domain_id: Optional[str] = typer.Option(None, "--domain-id", help="Filter by domain ID."),
+    inbox_id: Optional[str] = typer.Option(None, "--inbox-id", help="Filter by inbox ID."),
+    period: Optional[str] = typer.Option(None, "--period", help=PERIOD_HELP),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Get delivery metrics (sent, delivered, bounced, spam). GET /v1/delivery/metrics."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.get("/v1/delivery/metrics", params={
+            "domainId": domain_id,
+            "inboxId": inbox_id,
+            "period": period,
+        })
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    print_record(r.json(), json_output=json_output or state.should_json(), title="Delivery Metrics")
+
+
+@app.command("events")
+def delivery_events(
+    ctx: typer.Context,
+    domain_id: Optional[str] = typer.Option(None, "--domain-id", help="Filter by domain ID."),
+    inbox_id: Optional[str] = typer.Option(None, "--inbox-id", help="Filter by inbox ID."),
+    limit: Optional[int] = typer.Option(None, "--limit", help="Maximum results to return."),
+    cursor: Optional[str] = typer.Option(None, "--cursor", help="Pagination cursor."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Get delivery events (sent, bounce, complaint, open, click). GET /v1/delivery/events."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.get("/v1/delivery/events", params={
+            "domainId": domain_id,
+            "inboxId": inbox_id,
+            "limit": limit,
+            "cursor": cursor,
+        })
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    print_list(
+        r.json(),
+        json_output=json_output or state.should_json(),
+        title="Delivery Events",
+        columns=[
+            ("Type", "type"),
+            ("Email", "email"),
+            ("Message ID", "messageId"),
+            ("Timestamp", "timestamp"),
+        ],
+    )
+
+
+@app.command("suppressions")
+def delivery_suppressions(
+    ctx: typer.Context,
+    domain_id: Optional[str] = typer.Option(None, "--domain-id", help="Filter by domain ID."),
+    inbox_id: Optional[str] = typer.Option(None, "--inbox-id", help="Filter by inbox ID."),
+    limit: Optional[int] = typer.Option(None, "--limit", help="Maximum results."),
+    cursor: Optional[str] = typer.Option(None, "--cursor", help="Pagination cursor."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """List suppressed email addresses (bounces + spam complaints). GET /v1/delivery/suppressions."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.get("/v1/delivery/suppressions", params={
+            "domainId": domain_id,
+            "inboxId": inbox_id,
+            "limit": limit,
+            "cursor": cursor,
+        })
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    print_list(
+        r.json(),
+        json_output=json_output or state.should_json(),
+        title="Suppressed Addresses",
+        columns=[
+            ("Email", "email"),
+            ("Reason", "reason"),
+            ("Suppressed At", "suppressedAt"),
+        ],
+    )

commune_cli/commands/dmarc.py

@@ -0,0 +1,81 @@
+"""commune dmarc — DMARC reporting."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from ..client import CommuneClient
+from ..errors import api_error, auth_required_error, network_error, validation_error
+from ..output import print_list, print_record
+from ..state import AppState
+
+app = typer.Typer(help="DMARC reports and summary.", no_args_is_help=True)
+
+
+@app.command("reports")
+def dmarc_reports(
+    ctx: typer.Context,
+    domain: str = typer.Argument(..., help="Domain name to get DMARC reports for (e.g. example.com)."),
+    limit: Optional[int] = typer.Option(None, "--limit", help="Maximum reports to return."),
+    cursor: Optional[str] = typer.Option(None, "--cursor", help="Pagination cursor."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """List DMARC aggregate reports for a domain. GET /v1/dmarc/reports."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.get("/v1/dmarc/reports", params={
+            "domain": domain,
+            "limit": limit,
+            "cursor": cursor,
+        })
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    print_list(
+        r.json(),
+        json_output=json_output or state.should_json(),
+        title=f"DMARC Reports: {domain}",
+        columns=[
+            ("ID", "id"),
+            ("Reporter", "reporterOrg"),
+            ("Start", "dateRangeBegin"),
+            ("End", "dateRangeEnd"),
+            ("Records", "recordCount"),
+        ],
+    )
+
+
+@app.command("summary")
+def dmarc_summary(
+    ctx: typer.Context,
+    domain: str = typer.Argument(..., help="Domain name to summarize (e.g. example.com)."),
+    days: Optional[int] = typer.Option(None, "--days", help="Number of days to include (default: 30)."),
+    json_output: bool = typer.Option(False, "--json", help="Output JSON."),
+) -> None:
+    """Get a DMARC compliance summary for a domain. GET /v1/dmarc/summary."""
+    state: AppState = ctx.obj or AppState()
+    if not state.has_any_auth():
+        auth_required_error(json_output=json_output or state.should_json())
+
+    client = CommuneClient.from_state(state)
+    try:
+        r = client.get("/v1/dmarc/summary", params={
+            "domain": domain,
+            "days": days,
+        })
+    except Exception as exc:
+        network_error(exc, json_output=json_output or state.should_json())
+
+    if not r.is_success:
+        api_error(r, json_output=json_output or state.should_json())
+
+    print_record(r.json(), json_output=json_output or state.should_json(), title=f"DMARC Summary: {domain}")