commune-cli 0.1.0__tar.gz

commune_cli-0.1.0/.gitignore

@@ -0,0 +1,82 @@
+node_modules/
+**/node_modules/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+/lib/
+/lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+.venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Build artifacts
+dist/
+build/
+.next/
+.cache/
+
+# Remotion
+# ./remotion
+
+# Video files
+*.mp4
+*.mov
+*.avi
+*.mkv
+
+# Large/generated folders
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+pip-wheel-metadata/

commune_cli-0.1.0/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: commune-cli
+Version: 0.1.0
+Summary: Official CLI for the Commune email API — agent-native, pipe-friendly, covers every API surface.
+Project-URL: Homepage, https://commune.email
+Project-URL: Documentation, https://docs.commune.email
+Project-URL: Repository, https://github.com/commune-email/commune
+License: MIT
+Keywords: agent,ai,cli,commune,email
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# commune-cli
+
+Official command-line interface for the [Commune](https://commune.email) email API.
+
+Covers every API surface: domains, inboxes, messages, threads, attachments, search, delivery analytics, webhooks, DMARC, and data deletion.
+
+---
+
+## Install
+
+```bash
+pip install commune-cli
+```
+
+Requires Python ≥ 3.9.
+
+---
+
+## Quick Start
+
+```bash
+# Set your API key
+export COMMUNE_API_KEY=comm_...
+
+# Send an email
+commune messages send \
+  --to recipient@example.com \
+  --subject "Hello from CLI" \
+  --text "Sent from the terminal."
+
+# List inboxes
+commune inboxes list
+
+# JSON output (automatic when stdout is piped)
+commune inboxes list --json | jq '.data[].email'
+```
+
+---
+
+## Authentication
+
+Set your API key in one of these ways (highest priority wins):
+
+| Priority | Source |
+|----------|--------|
+| 1 | `--api-key` flag |
+| 2 | `COMMUNE_API_KEY` env var |
+| 3 | `~/.commune/config.toml` → `api_key` |
+
+Store permanently:
+
+```bash
+commune config set api_key comm_...
+commune config show
+```
+
+---
+
+## Output
+
+- **TTY**: rich tables and panels with color
+- **Piped / `--json`**: clean JSON to stdout; status messages to stderr
+
+```bash
+# JSON list format (always consistent)
+commune threads list --json
+# {"data": [...], "has_more": false, "next_cursor": null}
+```
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | API / validation error |
+| 2 | Auth error (401/403) |
+| 3 | Not found (404) |
+| 4 | Rate limit or plan gate (429/403) |
+| 5 | Network / connection error |
+
+---
+
+## Error Format (stderr)
+
+```json
+{"error": {"code": "not_found", "message": "Inbox not found.", "status_code": 404}}
+```
+
+---
+
+## Commands
+
+```
+commune
+├── config
+│   ├── set <key> <value>
+│   ├── get <key>
+│   ├── show [--reveal]
+│   ├── unset <key>
+│   └── path
+│
+├── domains
+│   ├── list [--limit] [--cursor]
+│   ├── get <domain-id>
+│   ├── create <name>
+│   ├── verify <domain-id>
+│   └── records <domain-id>
+│
+├── inboxes
+│   ├── list [--domain-id] [--limit] [--cursor]
+│   ├── get <inbox-id>
+│   ├── create [--local-part] [--domain-id] [--name] [--webhook-url]
+│   ├── update <inbox-id> [--name] [--webhook-url]
+│   ├── delete <inbox-id> --domain-id [--yes]
+│   ├── set-webhook <inbox-id> --domain-id --url
+│   └── extraction-schema
+│       ├── set <inbox-id> --domain-id --schema <json>
+│       └── remove <inbox-id> --domain-id
+│
+├── messages
+│   ├── send --to --subject [--text] [--html] [--from] [--inbox-id] [--domain-id]
+│   │        [--cc] [--bcc] [--reply-to] [--thread-id]
+│   └── list [--inbox-id] [--domain-id] [--sender] [--limit] [--order] [--before] [--after]
+│
+├── threads
+│   ├── list [--inbox-id] [--domain-id] [--limit] [--cursor] [--order]
+│   ├── messages <thread-id> [--limit] [--order] [--cursor]
+│   ├── metadata <thread-id>
+│   ├── set-status <thread-id> <open|needs_reply|waiting|closed>
+│   ├── assign <thread-id> [--to <user>]
+│   └── tags
+│       ├── add <thread-id> <tag...>
+│       └── remove <thread-id> <tag...>
+│
+├── attachments
+│   ├── upload <file>
+│   ├── get <attachment-id>
+│   └── url <attachment-id> [--expires-in]
+│
+├── search
+│   └── threads <query> [--inbox-id] [--domain-id] [--limit]
+│
+├── delivery
+│   ├── metrics [--domain-id] [--inbox-id] [--period]
+│   ├── events [--domain-id] [--inbox-id] [--limit]
+│   └── suppressions [--domain-id] [--inbox-id] [--limit]
+│
+├── webhooks
+│   ├── list [--inbox-id] [--status] [--endpoint] [--limit]
+│   ├── get <delivery-id>
+│   ├── retry <delivery-id>
+│   └── health
+│
+├── dmarc
+│   ├── reports <domain> [--limit]
+│   └── summary <domain> [--days]
+│
+└── data
+    ├── delete-request [--email] [--inbox-id] [--domain-id]
+    ├── delete-confirm <id> [--yes]
+    └── delete-status <id>
+```
+
+---
+
+## Global Flags
+
+```
+--api-key TEXT    API key (overrides env/config)
+--base-url TEXT   API base URL (default: https://api.commune.email)
+--json            Output raw JSON
+--quiet / -q      Suppress status messages
+--no-color        Disable color output
+--version / -V    Show version and exit
+```
+
+---
+
+## Config File
+
+Stored at `~/.commune/config.toml` (or `$COMMUNE_CONFIG_DIR/config.toml`).
+Created with `chmod 600` to protect your API key.
+
+```toml
+api_key = "comm_..."
+base_url = "https://api.commune.email"
+```
+
+---
+
+## Scripting
+
+```bash
+# Non-TTY → auto JSON
+inboxes=$(commune inboxes list)
+echo "$inboxes" | jq '.data[0].email'
+
+# Pipe body from stdin
+echo "Email body" | commune messages send \
+  --to user@example.com \
+  --subject "Automated" \
+  --text -
+
+# Exit code handling
+if commune messages send --to user@example.com --subject Test --text "Hi" --json; then
+  echo "Sent"
+else
+  echo "Failed: $?"
+fi
+```
+
+Full API reference: https://docs.commune.email

commune_cli-0.1.0/README.md

@@ -0,0 +1,214 @@
+# commune-cli
+
+Official command-line interface for the [Commune](https://commune.email) email API.
+
+Covers every API surface: domains, inboxes, messages, threads, attachments, search, delivery analytics, webhooks, DMARC, and data deletion.
+
+---
+
+## Install
+
+```bash
+pip install commune-cli
+```
+
+Requires Python ≥ 3.9.
+
+---
+
+## Quick Start
+
+```bash
+# Set your API key
+export COMMUNE_API_KEY=comm_...
+
+# Send an email
+commune messages send \
+  --to recipient@example.com \
+  --subject "Hello from CLI" \
+  --text "Sent from the terminal."
+
+# List inboxes
+commune inboxes list
+
+# JSON output (automatic when stdout is piped)
+commune inboxes list --json | jq '.data[].email'
+```
+
+---
+
+## Authentication
+
+Set your API key in one of these ways (highest priority wins):
+
+| Priority | Source |
+|----------|--------|
+| 1 | `--api-key` flag |
+| 2 | `COMMUNE_API_KEY` env var |
+| 3 | `~/.commune/config.toml` → `api_key` |
+
+Store permanently:
+
+```bash
+commune config set api_key comm_...
+commune config show
+```
+
+---
+
+## Output
+
+- **TTY**: rich tables and panels with color
+- **Piped / `--json`**: clean JSON to stdout; status messages to stderr
+
+```bash
+# JSON list format (always consistent)
+commune threads list --json
+# {"data": [...], "has_more": false, "next_cursor": null}
+```
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | API / validation error |
+| 2 | Auth error (401/403) |
+| 3 | Not found (404) |
+| 4 | Rate limit or plan gate (429/403) |
+| 5 | Network / connection error |
+
+---
+
+## Error Format (stderr)
+
+```json
+{"error": {"code": "not_found", "message": "Inbox not found.", "status_code": 404}}
+```
+
+---
+
+## Commands
+
+```
+commune
+├── config
+│   ├── set <key> <value>
+│   ├── get <key>
+│   ├── show [--reveal]
+│   ├── unset <key>
+│   └── path
+│
+├── domains
+│   ├── list [--limit] [--cursor]
+│   ├── get <domain-id>
+│   ├── create <name>
+│   ├── verify <domain-id>
+│   └── records <domain-id>
+│
+├── inboxes
+│   ├── list [--domain-id] [--limit] [--cursor]
+│   ├── get <inbox-id>
+│   ├── create [--local-part] [--domain-id] [--name] [--webhook-url]
+│   ├── update <inbox-id> [--name] [--webhook-url]
+│   ├── delete <inbox-id> --domain-id [--yes]
+│   ├── set-webhook <inbox-id> --domain-id --url
+│   └── extraction-schema
+│       ├── set <inbox-id> --domain-id --schema <json>
+│       └── remove <inbox-id> --domain-id
+│
+├── messages
+│   ├── send --to --subject [--text] [--html] [--from] [--inbox-id] [--domain-id]
+│   │        [--cc] [--bcc] [--reply-to] [--thread-id]
+│   └── list [--inbox-id] [--domain-id] [--sender] [--limit] [--order] [--before] [--after]
+│
+├── threads
+│   ├── list [--inbox-id] [--domain-id] [--limit] [--cursor] [--order]
+│   ├── messages <thread-id> [--limit] [--order] [--cursor]
+│   ├── metadata <thread-id>
+│   ├── set-status <thread-id> <open|needs_reply|waiting|closed>
+│   ├── assign <thread-id> [--to <user>]
+│   └── tags
+│       ├── add <thread-id> <tag...>
+│       └── remove <thread-id> <tag...>
+│
+├── attachments
+│   ├── upload <file>
+│   ├── get <attachment-id>
+│   └── url <attachment-id> [--expires-in]
+│
+├── search
+│   └── threads <query> [--inbox-id] [--domain-id] [--limit]
+│
+├── delivery
+│   ├── metrics [--domain-id] [--inbox-id] [--period]
+│   ├── events [--domain-id] [--inbox-id] [--limit]
+│   └── suppressions [--domain-id] [--inbox-id] [--limit]
+│
+├── webhooks
+│   ├── list [--inbox-id] [--status] [--endpoint] [--limit]
+│   ├── get <delivery-id>
+│   ├── retry <delivery-id>
+│   └── health
+│
+├── dmarc
+│   ├── reports <domain> [--limit]
+│   └── summary <domain> [--days]
+│
+└── data
+    ├── delete-request [--email] [--inbox-id] [--domain-id]
+    ├── delete-confirm <id> [--yes]
+    └── delete-status <id>
+```
+
+---
+
+## Global Flags
+
+```
+--api-key TEXT    API key (overrides env/config)
+--base-url TEXT   API base URL (default: https://api.commune.email)
+--json            Output raw JSON
+--quiet / -q      Suppress status messages
+--no-color        Disable color output
+--version / -V    Show version and exit
+```
+
+---
+
+## Config File
+
+Stored at `~/.commune/config.toml` (or `$COMMUNE_CONFIG_DIR/config.toml`).
+Created with `chmod 600` to protect your API key.
+
+```toml
+api_key = "comm_..."
+base_url = "https://api.commune.email"
+```
+
+---
+
+## Scripting
+
+```bash
+# Non-TTY → auto JSON
+inboxes=$(commune inboxes list)
+echo "$inboxes" | jq '.data[0].email'
+
+# Pipe body from stdin
+echo "Email body" | commune messages send \
+  --to user@example.com \
+  --subject "Automated" \
+  --text -
+
+# Exit code handling
+if commune messages send --to user@example.com --subject Test --text "Hi" --json; then
+  echo "Sent"
+else
+  echo "Failed: $?"
+fi
+```
+
+Full API reference: https://docs.commune.email

commune_cli-0.1.0/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-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-0.1.0/commune_cli/commands/__init__.py

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