fastsmtp-cli 0.6.0__py3-none-any.whl

fastsmtp_cli/commands/operations.py

@@ -0,0 +1,174 @@
+"""Operations commands (health, logs, test webhook)."""
+
+from typing import Annotated
+
+import typer
+
+from fastsmtp_cli.client import APIError, FastSMTPClient
+from fastsmtp_cli.commands.options import IncludeDeletedLogs
+from fastsmtp_cli.output import (
+    print_delivery_log,
+    print_delivery_logs_table,
+    print_error,
+    print_health,
+    print_ready,
+    print_success,
+    print_test_webhook_result,
+)
+
+app = typer.Typer(help="Operations (health, logs, test)")
+
+
+@app.command("health")
+def health(
+    profile: Annotated[
+        str | None,
+        typer.Option("--profile", "-p", help="Profile to use"),
+    ] = None,
+) -> None:
+    """Check server health."""
+    try:
+        with FastSMTPClient(profile_name=profile) as client:
+            result = client.health()
+            print_health(result)
+    except APIError as e:
+        print_error(e.detail)
+        raise typer.Exit(1) from e
+
+
+@app.command("ready")
+def ready(
+    profile: Annotated[
+        str | None,
+        typer.Option("--profile", "-p", help="Profile to use"),
+    ] = None,
+) -> None:
+    """Check server readiness (includes database check)."""
+    try:
+        with FastSMTPClient(profile_name=profile) as client:
+            result = client.ready()
+            print_ready(result)
+    except APIError as e:
+        print_error(e.detail)
+        raise typer.Exit(1) from e
+
+
+# Delivery log commands
+log_app = typer.Typer(help="Delivery log management")
+app.add_typer(log_app, name="log")
+
+
+@log_app.command("list")
+def list_logs(
+    domain_id: Annotated[str, typer.Argument(help="Domain ID")],
+    status: Annotated[
+        str | None,
+        typer.Option("--status", "-s", help="Filter by status"),
+    ] = None,
+    message_id: Annotated[
+        str | None,
+        typer.Option("--message-id", "-m", help="Filter by message ID"),
+    ] = None,
+    limit: Annotated[int, typer.Option("--limit", "-l", help="Max results")] = 50,
+    offset: Annotated[int, typer.Option("--offset", "-o", help="Offset")] = 0,
+    include_deleted: IncludeDeletedLogs = False,
+    profile: Annotated[
+        str | None,
+        typer.Option("--profile", "-p", help="Profile to use"),
+    ] = None,
+) -> None:
+    """List delivery logs for a domain (--include-deleted reads a deleted domain's history)."""
+    try:
+        with FastSMTPClient(profile_name=profile) as client:
+            logs = client.list_delivery_logs(
+                domain_id,
+                status=status,
+                message_id=message_id,
+                limit=limit,
+                offset=offset,
+                include_deleted=include_deleted,
+            )
+            if not logs:
+                print_error("No delivery logs found")
+                return
+            print_delivery_logs_table(logs)
+    except APIError as e:
+        print_error(e.detail)
+        raise typer.Exit(1) from e
+
+
+@log_app.command("get")
+def get_log(
+    log_id: Annotated[str, typer.Argument(help="Delivery log ID")],
+    profile: Annotated[
+        str | None,
+        typer.Option("--profile", "-p", help="Profile to use"),
+    ] = None,
+) -> None:
+    """Get delivery log details with payload."""
+    try:
+        with FastSMTPClient(profile_name=profile) as client:
+            log = client.get_delivery_log(log_id)
+            print_delivery_log(log)
+    except APIError as e:
+        print_error(e.detail)
+        raise typer.Exit(1) from e
+
+
+@log_app.command("retry")
+def retry_log(
+    log_id: Annotated[str, typer.Argument(help="Delivery log ID")],
+    profile: Annotated[
+        str | None,
+        typer.Option("--profile", "-p", help="Profile to use"),
+    ] = None,
+) -> None:
+    """Retry a failed, exhausted or cancelled delivery."""
+    try:
+        with FastSMTPClient(profile_name=profile) as client:
+            result = client.retry_delivery(log_id)
+            print_success(result.get("message", "Delivery queued for retry"))
+    except APIError as e:
+        print_error(e.detail)
+        raise typer.Exit(1) from e
+
+
+# Test webhook command
+@app.command("test-webhook")
+def test_webhook(
+    webhook_url: Annotated[str, typer.Argument(help="Webhook URL to test")],
+    from_addr: Annotated[
+        str,
+        typer.Option("--from", "-f", help="From address"),
+    ] = "test@example.com",
+    to_addr: Annotated[
+        str,
+        typer.Option("--to", "-t", help="To address"),
+    ] = "recipient@example.com",
+    subject: Annotated[
+        str,
+        typer.Option("--subject", "-s", help="Subject"),
+    ] = "Test Email",
+    body: Annotated[
+        str,
+        typer.Option("--body", "-b", help="Body text"),
+    ] = "This is a test email from FastSMTP.",
+    profile: Annotated[
+        str | None,
+        typer.Option("--profile", "-p", help="Profile to use"),
+    ] = None,
+) -> None:
+    """Test a webhook URL by sending a test payload."""
+    try:
+        with FastSMTPClient(profile_name=profile) as client:
+            result = client.test_webhook(
+                webhook_url=webhook_url,
+                from_address=from_addr,
+                to_address=to_addr,
+                subject=subject,
+                body=body,
+            )
+            print_test_webhook_result(result)
+    except APIError as e:
+        print_error(e.detail)
+        raise typer.Exit(1) from e

fastsmtp_cli/commands/options.py

@@ -0,0 +1,84 @@
+"""Shared option aliases and helpers for the command modules."""
+
+from typing import Annotated
+
+import typer
+
+from fastsmtp_cli.client import UNSET, NullableStr
+
+#: ``--include-deleted`` on every list/get that can show tombstones. The server
+#: gates the flag at the delete role for that resource: below it a caller with
+#: no access at all gets the same 403 whether or not a tombstone exists, and a
+#: member of the domain gets a 404 once it is deleted.
+IncludeDeleted = Annotated[
+    bool,
+    typer.Option("--include-deleted", help="Also show deleted (restorable) entries"),
+]
+
+#: The same flag on ``auth keys``: keys are never restorable, and the listing
+#: also covers keys retired before soft delete existed.
+IncludeDeletedKeys = Annotated[
+    bool,
+    typer.Option(
+        "--include-deleted", help="Also show deleted and retired keys (keys cannot be restored)"
+    ),
+]
+
+#: The same flag on ``ops log list``: log rows are never deleted, so the flag
+#: only resolves a deleted domain (owner or superuser) to read its history.
+IncludeDeletedLogs = Annotated[
+    bool,
+    typer.Option(
+        "--include-deleted",
+        help="Read the history of a deleted domain (owner or superuser); log rows themselves "
+        "are never deleted",
+    ),
+]
+
+#: ``--purge`` on every delete. A purge is a second step: it only works on a row
+#: that is already deleted (the server answers 409 otherwise), and it runs the
+#: hard-delete cascades that soft delete exists to avoid.
+Purge = Annotated[
+    bool,
+    typer.Option(
+        "--purge",
+        help="Permanently delete an already-deleted entry (superuser only, cannot be undone)",
+    ),
+]
+
+
+def confirm_delete(kind: str, label: str, *, force: bool, purge: bool) -> None:
+    """Ask before a delete unless ``--force``; exit 0 when the operator declines.
+
+    Shared by the user, domain and recipient ``delete`` commands. A soft
+    delete keeps the pre-0.5.0 prompt; a purge gets its own, spelling out that
+    it cannot be undone.
+    """
+    if force:
+        return
+    if purge:
+        prompt = f"Permanently delete {kind} {label}? This cannot be undone."
+    else:
+        prompt = f"Delete {kind} {label}?"
+    if not typer.confirm(prompt):
+        raise typer.Exit(0)
+
+
+def clearable_str(option: str | None) -> NullableStr:
+    """Map a nullable-string option onto the client's tri-state value.
+
+    CLI-wide convention for options backed by a nullable string column: leaving
+    the option off (``None``) leaves the column untouched, passing an empty
+    string (``--option ''``) clears it (the client sends an explicit JSON
+    null), and any other value sets it.
+
+    This is the string counterpart of the ``true``/``false``/``inherit``
+    tri-state used for nullable boolean flags (see ``commands/domains.py``);
+    strings need no enum because the empty string is not an otherwise
+    meaningful value for these columns.
+    """
+    if option is None:
+        return UNSET
+    if option == "":
+        return None
+    return option

fastsmtp_cli/commands/recipients.py

@@ -0,0 +1,223 @@
+"""Recipient management commands.
+
+Recipients are nested under a domain on the server, so every command that
+addresses a single recipient takes the domain ID as well as the recipient ID.
+
+``delete`` is a soft delete: the address stops receiving mail and its queued
+deliveries are cancelled, but ``restore`` brings it back (cancelled deliveries
+stay cancelled; re-queue them with ``fsmtp ops log retry``). ``delete
+--purge`` removes an already-deleted recipient for good.
+"""
+
+from typing import Annotated
+
+import typer
+
+from fastsmtp_cli.client import APIError, FastSMTPClient
+from fastsmtp_cli.commands.options import IncludeDeleted, Purge, clearable_str, confirm_delete
+from fastsmtp_cli.output import (
+    print_deleted,
+    print_error,
+    print_recipient,
+    print_recipients_table,
+    print_success,
+)
+
+app = typer.Typer(help="Recipient management")
+
+HeaderOption = Annotated[
+    list[str] | None,
+    typer.Option("--header", "-H", help="Webhook header as KEY=VALUE (can be repeated)"),
+]
+
+
+def parse_headers(headers: list[str] | None) -> dict[str, str] | None:
+    """Parse repeated ``KEY=VALUE`` options into a headers mapping.
+
+    Raises:
+        typer.Exit: with status 1 if an entry is not ``KEY=VALUE``
+    """
+    if not headers:
+        return None
+    parsed: dict[str, str] = {}
+    for entry in headers:
+        key, separator, value = entry.partition("=")
+        if not separator or not key.strip():
+            print_error(f"Invalid header '{entry}'. Use KEY=VALUE.")
+            raise typer.Exit(1)
+        parsed[key.strip()] = value.strip()
+    return parsed
+
+
+@app.command("list")
+def list_recipients(
+    domain_id: Annotated[str, typer.Argument(help="Domain ID")],
+    include_deleted: IncludeDeleted = False,
+    profile: Annotated[
+        str | None,
+        typer.Option("--profile", "-p", help="Profile to use"),
+    ] = None,
+) -> None:
+    """List recipients for a domain."""
+    try:
+        with FastSMTPClient(profile_name=profile) as client:
+            recipients = client.list_recipients(domain_id, include_deleted=include_deleted)
+            if not recipients:
+                print_error("No recipients found")
+                return
+            print_recipients_table(recipients)
+    except APIError as e:
+        print_error(e.detail)
+        raise typer.Exit(1) from e
+
+
+@app.command("get")
+def get_recipient(
+    domain_id: Annotated[str, typer.Argument(help="Domain ID")],
+    recipient_id: Annotated[str, typer.Argument(help="Recipient ID")],
+    include_deleted: IncludeDeleted = False,
+    profile: Annotated[
+        str | None,
+        typer.Option("--profile", "-p", help="Profile to use"),
+    ] = None,
+) -> None:
+    """Get recipient details (a deleted recipient is not found without --include-deleted)."""
+    try:
+        with FastSMTPClient(profile_name=profile) as client:
+            recipient = client.get_recipient(
+                domain_id, recipient_id, include_deleted=include_deleted
+            )
+            print_recipient(recipient)
+    except APIError as e:
+        print_error(e.detail)
+        raise typer.Exit(1) from e
+
+
+@app.command("create")
+def create_recipient(
+    domain_id: Annotated[str, typer.Argument(help="Domain ID")],
+    webhook_url: Annotated[str, typer.Argument(help="Webhook URL")],
+    local_part: Annotated[
+        str | None,
+        typer.Option("--local", "-l", help="Local part (omit for catch-all)"),
+    ] = None,
+    headers: HeaderOption = None,
+    profile: Annotated[
+        str | None,
+        typer.Option("--profile", "-p", help="Profile to use"),
+    ] = None,
+) -> None:
+    """Create a new recipient."""
+    webhook_headers = parse_headers(headers)
+
+    try:
+        with FastSMTPClient(profile_name=profile) as client:
+            recipient = client.create_recipient(
+                domain_id=domain_id,
+                webhook_url=webhook_url,
+                local_part=local_part,
+                webhook_headers=webhook_headers,
+            )
+            address = local_part if local_part else "* (catch-all)"
+            print_success(f"Recipient '{address}' created")
+            print_recipient(recipient)
+    except APIError as e:
+        print_error(e.detail)
+        raise typer.Exit(1) from e
+
+
+@app.command("update")
+def update_recipient(
+    domain_id: Annotated[str, typer.Argument(help="Domain ID")],
+    recipient_id: Annotated[str, typer.Argument(help="Recipient ID")],
+    local_part: Annotated[
+        str | None,
+        typer.Option("--local", "-l", help="Local part; pass '' to clear it (catch-all)"),
+    ] = None,
+    webhook_url: Annotated[
+        str | None,
+        typer.Option("--webhook", "-w", help="Webhook URL"),
+    ] = None,
+    enabled: Annotated[
+        bool | None,
+        typer.Option("--enabled/--disabled", help="Enable or disable recipient"),
+    ] = None,
+    headers: HeaderOption = None,
+    profile: Annotated[
+        str | None,
+        typer.Option("--profile", "-p", help="Profile to use"),
+    ] = None,
+) -> None:
+    """Update a recipient."""
+    if all(value is None for value in [local_part, webhook_url, enabled, headers]):
+        print_error("At least one option must be provided")
+        raise typer.Exit(1)
+
+    webhook_headers = parse_headers(headers)
+
+    try:
+        with FastSMTPClient(profile_name=profile) as client:
+            recipient = client.update_recipient(
+                domain_id=domain_id,
+                recipient_id=recipient_id,
+                local_part=clearable_str(local_part),
+                webhook_url=webhook_url,
+                is_enabled=enabled,
+                webhook_headers=webhook_headers,
+            )
+            print_success("Recipient updated")
+            print_recipient(recipient)
+    except APIError as e:
+        print_error(e.detail)
+        raise typer.Exit(1) from e
+
+
+@app.command("delete")
+def delete_recipient(
+    domain_id: Annotated[str, typer.Argument(help="Domain ID")],
+    recipient_id: Annotated[str, typer.Argument(help="Recipient ID")],
+    force: Annotated[
+        bool,
+        typer.Option("--force", "-f", help="Skip confirmation"),
+    ] = False,
+    purge: Purge = False,
+    profile: Annotated[
+        str | None,
+        typer.Option("--profile", "-p", help="Profile to use"),
+    ] = None,
+) -> None:
+    """Delete a recipient (restorable), or permanently purge an already-deleted one."""
+    confirm_delete("recipient", recipient_id, force=force, purge=purge)
+
+    try:
+        with FastSMTPClient(profile_name=profile) as client:
+            client.delete_recipient(domain_id, recipient_id, purge=purge)
+            print_deleted(
+                "recipient",
+                recipient_id,
+                purge=purge,
+                restore_command=f"fsmtp recipient restore {domain_id} {recipient_id}",
+            )
+    except APIError as e:
+        print_error(e.detail)
+        raise typer.Exit(1) from e
+
+
+@app.command("restore")
+def restore_recipient(
+    domain_id: Annotated[str, typer.Argument(help="Domain ID")],
+    recipient_id: Annotated[str, typer.Argument(help="Recipient ID")],
+    profile: Annotated[
+        str | None,
+        typer.Option("--profile", "-p", help="Profile to use"),
+    ] = None,
+) -> None:
+    """Restore a deleted recipient (the domain itself must not be deleted)."""
+    try:
+        with FastSMTPClient(profile_name=profile) as client:
+            recipient = client.restore_recipient(domain_id, recipient_id)
+            print_success("Recipient restored")
+            print_recipient(recipient)
+    except APIError as e:
+        print_error(e.detail)
+        raise typer.Exit(1) from e