hound-cli 0.1.0__py3-none-any.whl

hound_cli/inbox/command.py

@@ -0,0 +1,212 @@
+"""Coordinate read-only access to account-local email and SMS inboxes."""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime, timedelta
+
+import click
+import questionary
+import urllib3
+from botocore.exceptions import BotoCoreError, ClientError
+
+from hound_cli.aws import _aws_account_id, aws_client, operator_only
+from hound_cli.inbox.email import (
+    EmailSummary,
+    ParsedEmail,
+    email_bucket_name,
+    list_email_messages,
+    read_email_message,
+    validate_agent_recipient,
+)
+from hound_cli.inbox.sms import SmsMessage, list_sms_messages, load_twilio_credentials, read_sms_message
+from hound_cli.roster import load_roster, validate_phone_number
+from hound_cli.ui import MENU_STYLE
+
+DEFAULT_LOOKBACK = "24h"
+_DURATION = re.compile(r"^(?P<amount>[1-9][0-9]*)(?P<unit>[mhd])$")
+
+
+def parse_lookback(value: str) -> timedelta:
+    """Parse a compact positive duration, capped by the seven-day inbox window."""
+    match = _DURATION.fullmatch(value.strip().lower())
+    if match is None:
+        raise click.BadParameter("use a duration such as 30m, 2h, or 7d", param_hint="--since")
+    amount = int(match.group("amount"))
+    unit = match.group("unit")
+    duration = timedelta(**{{"m": "minutes", "h": "hours", "d": "days"}[unit]: amount})
+    if duration > timedelta(days=7):
+        raise click.BadParameter("cannot exceed the seven-day inbox window", param_hint="--since")
+    return duration
+
+
+def _safe_terminal(value: str) -> str:
+    """Remove terminal control characters from untrusted message text."""
+    return "".join(character for character in value if character in "\n\t" or character.isprintable())
+
+
+def _select_agent(roster: dict, requested_agent: str | None) -> tuple[str, dict]:
+    if requested_agent is not None:
+        if requested_agent not in roster:
+            available = ", ".join(sorted(roster))
+            raise click.ClickException(
+                f"Agent {requested_agent!r} is not in the roster. Available agents: {available}."
+            )
+        return requested_agent, roster[requested_agent]
+
+    choices = [
+        questionary.Choice(
+            title=" — ".join(value for value in (agent_id, agent["email"], agent.get("phone_number")) if value),
+            value=agent_id,
+        )
+        for agent_id, agent in sorted(roster.items())
+    ]
+    agent_id = questionary.select("Agent inbox", choices=choices, style=MENU_STYLE).unsafe_ask()
+    if agent_id is None:
+        raise click.Abort()
+    return agent_id, roster[agent_id]
+
+
+def _select_channel(agent_id: str, agent: dict, requested_channel: str | None) -> str:
+    channels = ["email"]
+    if agent.get("phone_number"):
+        channels.append("sms")
+    if requested_channel is not None:
+        if requested_channel not in channels:
+            raise click.ClickException(f"Agent {agent_id!r} does not have {requested_channel} configured.")
+        return requested_channel
+    if len(channels) == 1:
+        return channels[0]
+    selected = questionary.select("Inbox channel", choices=channels, style=MENU_STYLE).unsafe_ask()
+    if selected is None:
+        raise click.Abort()
+    return selected
+
+
+def _select_email(messages: list[EmailSummary]) -> EmailSummary:
+    choices = [
+        questionary.Choice(
+            title=(
+                f"{message.received_at.astimezone().strftime('%Y-%m-%d %H:%M:%S %Z')} — "
+                f"{_safe_terminal(message.sender) or '(unknown sender)'} — "
+                f"{_safe_terminal(message.subject) or '(no subject)'} — {message.email_id[-8:]}"
+            ),
+            value=message,
+        )
+        for message in messages
+    ]
+    message = questionary.select("Message", choices=choices, style=MENU_STYLE).unsafe_ask()
+    if message is None:
+        raise click.Abort()
+    return message
+
+
+def _select_sms(messages: list[SmsMessage]) -> SmsMessage:
+    choices = [
+        questionary.Choice(
+            title=(
+                f"{message.received_at.astimezone().strftime('%Y-%m-%d %H:%M:%S %Z')} — "
+                f"{_safe_terminal(message.sender) or '(unknown sender)'} — {message.sid[-8:]}"
+            ),
+            value=message,
+        )
+        for message in messages
+    ]
+    message = questionary.select("Message", choices=choices, style=MENU_STYLE).unsafe_ask()
+    if message is None:
+        raise click.Abort()
+    return message
+
+
+def _display_email(agent_id: str, recipient: str, summary: EmailSummary, email: ParsedEmail) -> None:
+    click.echo(f"\nAgent:      {agent_id}")
+    click.echo("Channel:    email")
+    click.echo(f"Inbox:      {recipient}")
+    click.echo(f"Received:   {summary.received_at.astimezone().isoformat()}")
+    click.echo(f"From:       {_safe_terminal(email.sender) or '—'}")
+    click.echo(f"To:         {_safe_terminal(', '.join(email.recipients)) or '—'}")
+    click.echo(f"Sent:       {_safe_terminal(email.sent_date) or '—'}")
+    click.echo(f"Subject:    {_safe_terminal(email.subject) or '—'}")
+    click.echo(f"Message-ID: {_safe_terminal(email.message_id) or '—'}")
+    click.echo("\nBody:\n")
+    click.echo(_safe_terminal(email.body) or "(No readable text body.)")
+    if email.links:
+        click.echo("\nLinks:")
+        for link in email.links:
+            click.echo(f"  {_safe_terminal(link)}")
+
+
+def _display_sms(agent_id: str, message: SmsMessage) -> None:
+    click.echo(f"\nAgent:       {agent_id}")
+    click.echo("Channel:     sms")
+    click.echo(f"Inbox:       {_safe_terminal(message.recipient)}")
+    click.echo(f"Received:    {message.received_at.astimezone().isoformat()}")
+    click.echo(f"From:        {_safe_terminal(message.sender) or '—'}")
+    click.echo(f"To:          {_safe_terminal(message.recipient)}")
+    click.echo(f"Status:      {_safe_terminal(message.status) or '—'}")
+    click.echo(f"Message SID: {_safe_terminal(message.sid)}")
+    click.echo("\nBody:\n")
+    click.echo(_safe_terminal(message.body) or "(Empty message body.)")
+
+
+def _show_email(agent_id: str, agent: dict, cutoff: datetime, since: str) -> None:
+    recipient = validate_agent_recipient(agent_id, agent["email"])
+    bucket = email_bucket_name(_aws_account_id())
+    s3 = aws_client("s3")
+    try:
+        messages = list_email_messages(s3, bucket=bucket, agent_id=agent_id, cutoff=cutoff)
+        if not messages:
+            raise click.ClickException(
+                f"No email messages for {recipient} in the last {since}. Send a message or increase --since."
+            )
+        summary = _select_email(messages)
+        email = read_email_message(
+            s3,
+            bucket=bucket,
+            agent_id=agent_id,
+            email_id=summary.email_id,
+            cutoff=cutoff,
+        )
+    except (BotoCoreError, ClientError, KeyError) as exc:
+        raise click.ClickException("Could not read the agent email inbox for this account.") from exc
+    _display_email(agent_id, recipient, summary, email)
+
+
+def _show_sms(agent_id: str, agent: dict, secrets, cutoff: datetime, since: str) -> None:
+    phone_number = validate_phone_number(agent["phone_number"])
+    try:
+        credentials = load_twilio_credentials(secrets)
+    except (BotoCoreError, ClientError, KeyError) as exc:
+        raise click.ClickException("Could not load the Twilio inbox credential for this account.") from exc
+    http = urllib3.PoolManager()
+    messages = list_sms_messages(http, credentials, recipient=phone_number, cutoff=cutoff)
+    if not messages:
+        raise click.ClickException(
+            f"No SMS messages for {phone_number} in the last {since}. Send a message or increase --since."
+        )
+    selected = _select_sms(messages)
+    message = read_sms_message(
+        http,
+        credentials,
+        recipient=phone_number,
+        message_sid=selected.sid,
+        cutoff=cutoff,
+    )
+    _display_sms(agent_id, message)
+
+
+@click.command("inbox")
+@click.option("--agent", "agent_id", help="Stable agent ID from hound/agents.")
+@click.option("--channel", type=click.Choice(("email", "sms"), case_sensitive=False), help="Inbox channel.")
+@click.option("--since", default=DEFAULT_LOOKBACK, show_default=True, help="Recent window: 30m, 2h, or up to 7d.")
+@operator_only
+def inbox(agent_id: str | None, channel: str | None, since: str) -> None:
+    """Read recent agent email or SMS for this account."""
+    cutoff = datetime.now(UTC) - parse_lookback(since)
+    secrets = aws_client("secretsmanager")
+    selected_agent, agent = _select_agent(load_roster(secrets), agent_id)
+    selected_channel = _select_channel(selected_agent, agent, channel)
+    if selected_channel == "email":
+        _show_email(selected_agent, agent, cutoff, since)
+    else:
+        _show_sms(selected_agent, agent, secrets, cutoff, since)

hound_cli/inbox/email.py

@@ -0,0 +1,210 @@
+"""Read account-local agent email messages from SES-backed S3 storage."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import datetime
+from email.message import Message
+from email.parser import BytesParser
+from email.policy import default
+from email.utils import getaddresses
+from html.parser import HTMLParser
+
+import click
+
+from hound_cli.roster import validate_agent_id
+
+EMAIL_MESSAGE_LIMIT = 20
+_URL = re.compile(r"https?://[^\s<>\"']+")
+
+
+@dataclass(frozen=True)
+class EmailSummary:
+    """Email metadata shown while selecting a stored message."""
+
+    email_id: str
+    received_at: datetime
+    subject: str
+    sender: str
+
+
+@dataclass(frozen=True)
+class ParsedEmail:
+    """Decoded operator-facing email content."""
+
+    subject: str
+    sender: str
+    recipients: tuple[str, ...]
+    sent_date: str
+    message_id: str
+    body: str
+    links: tuple[str, ...]
+
+
+class _ReadableHtml(HTMLParser):
+    """Extract readable text and links without rendering untrusted HTML."""
+
+    _BLOCK_TAGS = frozenset({"br", "div", "li", "p", "table", "tr"})
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self._ignored_depth = 0
+        self.text: list[str] = []
+        self.links: list[str] = []
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        tag = tag.lower()
+        if tag in {"script", "style"}:
+            self._ignored_depth += 1
+            return
+        if self._ignored_depth:
+            return
+        if tag in self._BLOCK_TAGS:
+            self.text.append("\n")
+        if tag == "a":
+            href = dict(attrs).get("href")
+            if href and href.startswith(("http://", "https://")):
+                self.links.append(href)
+
+    def handle_endtag(self, tag: str) -> None:
+        tag = tag.lower()
+        if tag in {"script", "style"} and self._ignored_depth:
+            self._ignored_depth -= 1
+        elif not self._ignored_depth and tag in self._BLOCK_TAGS:
+            self.text.append("\n")
+
+    def handle_data(self, data: str) -> None:
+        if not self._ignored_depth:
+            self.text.append(data)
+
+
+def email_bucket_name(account_id: str) -> str:
+    """Return the deterministic account-local raw-email bucket name."""
+    if not re.fullmatch(r"[0-9]{12}", account_id):
+        raise ValueError("AWS account ID must contain exactly 12 digits.")
+    return f"hound-agent-email-{account_id}"
+
+
+def _agent_prefix(agent_id: str) -> str:
+    return f"{validate_agent_id(agent_id)}/"
+
+
+def validate_agent_recipient(agent_id: str, recipient: str) -> str:
+    """Require the roster recipient local part to match its stable agent ID."""
+    validate_agent_id(agent_id)
+    normalized = recipient.strip().lower()
+    expected_suffix = ".hound-agents.com"
+    local_part, separator, domain = normalized.partition("@")
+    if separator != "@" or local_part != agent_id or not domain.endswith(expected_suffix):
+        raise click.ClickException(
+            f"Agent {agent_id!r} must use {agent_id}@<domain-label>.hound-agents.com in hound/agents."
+        )
+    domain_label = domain[: -len(expected_suffix)]
+    try:
+        validate_agent_id(domain_label)
+    except click.ClickException as exc:
+        raise click.ClickException(f"Agent {agent_id!r} has an invalid Hound email domain in hound/agents.") from exc
+    return normalized
+
+
+def _addresses(message: Message) -> tuple[str, ...]:
+    headers = [*message.get_all("to", []), *message.get_all("cc", [])]
+    return tuple(address for _name, address in getaddresses(headers) if address)
+
+
+def _content(part: Message | None) -> str:
+    if part is None:
+        return ""
+    try:
+        content = part.get_content()
+    except LookupError, UnicodeDecodeError:
+        payload = part.get_payload(decode=True) or b""
+        return payload.decode("utf-8", errors="replace")
+    return content if isinstance(content, str) else content.decode("utf-8", errors="replace")
+
+
+def parse_email(raw_message: bytes) -> ParsedEmail:
+    """Decode one raw RFC 5322 message without executing or rendering HTML."""
+    message = BytesParser(policy=default).parsebytes(raw_message)
+    plain_part = message.get_body(preferencelist=("plain",))
+    html_part = message.get_body(preferencelist=("html",))
+
+    body = _content(plain_part)
+    links: list[str] = []
+    if html_part is not None:
+        parser = _ReadableHtml()
+        parser.feed(_content(html_part))
+        links.extend(parser.links)
+        if not body:
+            body = "".join(parser.text)
+
+    body = re.sub(r"[ \t]+\n", "\n", body)
+    body = re.sub(r"\n{3,}", "\n\n", body).strip()
+    links.extend(_URL.findall(body))
+
+    return ParsedEmail(
+        subject=str(message.get("subject", "")),
+        sender=str(message.get("from", "")),
+        recipients=_addresses(message),
+        sent_date=str(message.get("date", "")),
+        message_id=str(message.get("message-id", "")),
+        body=body,
+        links=tuple(dict.fromkeys(link.rstrip(".,);]") for link in links)),
+    )
+
+
+def list_email_messages(
+    s3,
+    *,
+    bucket: str,
+    agent_id: str,
+    cutoff: datetime,
+    limit: int = EMAIL_MESSAGE_LIMIT,
+) -> list[EmailSummary]:
+    """List recent messages beneath exactly one agent prefix."""
+    prefix = _agent_prefix(agent_id)
+    objects: list[dict] = []
+    continuation_token: str | None = None
+    while True:
+        request = {"Bucket": bucket, "Prefix": prefix}
+        if continuation_token:
+            request["ContinuationToken"] = continuation_token
+        response = s3.list_objects_v2(**request)
+        objects.extend(item for item in response.get("Contents", []) if item["LastModified"] >= cutoff)
+        if not response.get("IsTruncated"):
+            break
+        continuation_token = response.get("NextContinuationToken")
+        if not continuation_token:
+            raise click.ClickException("S3 returned a truncated inbox listing without a continuation token.")
+
+    objects.sort(key=lambda item: item["LastModified"], reverse=True)
+    messages: list[EmailSummary] = []
+    for item in objects:
+        object_key = item["Key"]
+        email_id = object_key[len(prefix) :] if object_key.startswith(prefix) else ""
+        if not email_id or "/" in email_id:
+            continue
+        parsed = parse_email(s3.get_object(Bucket=bucket, Key=object_key)["Body"].read())
+        messages.append(
+            EmailSummary(
+                email_id=email_id,
+                received_at=item["LastModified"],
+                subject=parsed.subject,
+                sender=parsed.sender,
+            )
+        )
+        if len(messages) == limit:
+            break
+    return messages
+
+
+def read_email_message(s3, *, bucket: str, agent_id: str, email_id: str, cutoff: datetime) -> ParsedEmail:
+    """Read one recent message while re-enforcing its recipient prefix."""
+    if not email_id or "/" in email_id or email_id in {".", ".."}:
+        raise click.ClickException("Invalid inbox message ID.")
+    object_key = f"{_agent_prefix(agent_id)}{email_id}"
+    response = s3.get_object(Bucket=bucket, Key=object_key)
+    if response["LastModified"] < cutoff:
+        raise click.ClickException("That inbox message is older than the requested --since window.")
+    return parse_email(response["Body"].read())

hound_cli/inbox/sms.py

@@ -0,0 +1,190 @@
+"""Read account-local agent SMS messages from Twilio."""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+
+import click
+import urllib3
+
+from hound_cli.aws import get_secret
+from hound_cli.roster import validate_phone_number
+
+TWILIO_SECRET_ID = "hound/twilio"
+MAX_MESSAGES = 20
+_ACCOUNT_SID = re.compile(r"^AC[0-9a-fA-F]{32}$")
+_API_KEY_SID = re.compile(r"^SK[0-9a-fA-F]{32}$")
+_MESSAGE_SID = re.compile(r"^(?:SM|MM)[0-9a-fA-F]{32}$")
+_TWILIO_FIELDS = frozenset({"TWILIO_ACCOUNT_SID", "TWILIO_API_KEY", "TWILIO_API_SECRET"})
+
+
+@dataclass(frozen=True)
+class TwilioCredentials:
+    """Restricted credentials for one managed account's Twilio subaccount."""
+
+    account_sid: str
+    api_key_sid: str
+    api_secret: str
+
+
+@dataclass(frozen=True)
+class SmsMessage:
+    """Operator-facing Twilio message."""
+
+    sid: str
+    received_at: datetime
+    sender: str
+    recipient: str
+    direction: str
+    status: str
+    body: str
+
+
+def load_twilio_credentials(secrets_client) -> TwilioCredentials:
+    """Load and validate the account-local read-only Twilio credential."""
+    try:
+        secret = get_secret(secrets_client, TWILIO_SECRET_ID)
+    except (TypeError, json.JSONDecodeError) as exc:
+        raise click.ClickException(f"'{TWILIO_SECRET_ID}' must contain a JSON object.") from exc
+    if secret is None:
+        raise click.ClickException(f"Twilio credentials were not found at '{TWILIO_SECRET_ID}'.")
+    if not isinstance(secret, dict) or not _TWILIO_FIELDS.issubset(secret):
+        raise click.ClickException(f"'{TWILIO_SECRET_ID}' must contain: {', '.join(sorted(_TWILIO_FIELDS))}.")
+
+    values = {key: secret[key].strip() if isinstance(secret[key], str) else "" for key in _TWILIO_FIELDS}
+    if not _ACCOUNT_SID.fullmatch(values["TWILIO_ACCOUNT_SID"]):
+        raise click.ClickException(f"'{TWILIO_SECRET_ID}' contains an invalid TWILIO_ACCOUNT_SID.")
+    if not _API_KEY_SID.fullmatch(values["TWILIO_API_KEY"]):
+        raise click.ClickException(f"'{TWILIO_SECRET_ID}' contains an invalid TWILIO_API_KEY.")
+    if not values["TWILIO_API_SECRET"]:
+        raise click.ClickException(f"'{TWILIO_SECRET_ID}' contains an empty TWILIO_API_SECRET.")
+    return TwilioCredentials(
+        account_sid=values["TWILIO_ACCOUNT_SID"],
+        api_key_sid=values["TWILIO_API_KEY"],
+        api_secret=values["TWILIO_API_SECRET"],
+    )
+
+
+def _authorization(credentials: TwilioCredentials) -> str:
+    value = f"{credentials.api_key_sid}:{credentials.api_secret}".encode()
+    return f"Basic {base64.b64encode(value).decode('ascii')}"
+
+
+def _request_json(http, credentials: TwilioCredentials, url: str, *, fields: dict | None = None) -> dict:
+    try:
+        response = http.request(
+            "GET",
+            url,
+            fields=fields,
+            headers={"Accept": "application/json", "Authorization": _authorization(credentials)},
+            timeout=urllib3.Timeout(connect=5, read=15),
+            retries=False,
+        )
+    except urllib3.exceptions.HTTPError as exc:
+        raise click.ClickException("Could not reach the Twilio inbox for this account.") from exc
+    if response.status != 200:
+        raise click.ClickException(f"Twilio inbox request failed with HTTP {response.status}.")
+    try:
+        value = json.loads(response.data)
+    except (TypeError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise click.ClickException("Twilio returned an invalid inbox response.") from exc
+    if not isinstance(value, dict):
+        raise click.ClickException("Twilio returned an invalid inbox response.")
+    return value
+
+
+def _received_at(message: dict) -> datetime:
+    raw = message.get("date_sent") or message.get("date_created")
+    if not isinstance(raw, str):
+        raise ValueError("missing message timestamp")
+    received_at = parsedate_to_datetime(raw)
+    if received_at.tzinfo is None:
+        received_at = received_at.replace(tzinfo=UTC)
+    return received_at.astimezone(UTC)
+
+
+def _parse_message(message: dict) -> SmsMessage:
+    sid = message.get("sid")
+    sender = message.get("from")
+    recipient = message.get("to")
+    direction = message.get("direction")
+    status = message.get("status")
+    body = message.get("body")
+    if not isinstance(sid, str) or not _MESSAGE_SID.fullmatch(sid):
+        raise ValueError("invalid message SID")
+    if not all(isinstance(value, str) for value in (sender, recipient, direction, status, body)):
+        raise ValueError("invalid message fields")
+    return SmsMessage(
+        sid=sid,
+        received_at=_received_at(message),
+        sender=sender,
+        recipient=recipient,
+        direction=direction,
+        status=status,
+        body=body,
+    )
+
+
+def list_sms_messages(
+    http,
+    credentials: TwilioCredentials,
+    *,
+    recipient: str,
+    cutoff: datetime,
+) -> list[SmsMessage]:
+    """List recent inbound messages for exactly one roster phone number."""
+    recipient = validate_phone_number(recipient)
+    url = f"https://api.twilio.com/2010-04-01/Accounts/{credentials.account_sid}/Messages.json"
+    payload = _request_json(
+        http,
+        credentials,
+        url,
+        fields={"To": recipient, "PageSize": MAX_MESSAGES},
+    )
+    raw_messages = payload.get("messages")
+    if not isinstance(raw_messages, list):
+        raise click.ClickException("Twilio returned an invalid message list.")
+
+    messages: list[SmsMessage] = []
+    for raw_message in raw_messages:
+        if not isinstance(raw_message, dict):
+            continue
+        if raw_message.get("direction") != "inbound" or raw_message.get("to") != recipient:
+            continue
+        try:
+            message = _parse_message(raw_message)
+        except TypeError, ValueError:
+            continue
+        if message.received_at >= cutoff:
+            messages.append(message)
+    messages.sort(key=lambda message: message.received_at, reverse=True)
+    return messages[:MAX_MESSAGES]
+
+
+def read_sms_message(
+    http,
+    credentials: TwilioCredentials,
+    *,
+    recipient: str,
+    message_sid: str,
+    cutoff: datetime,
+) -> SmsMessage:
+    """Read one recent message while re-enforcing its exact recipient."""
+    recipient = validate_phone_number(recipient)
+    if not _MESSAGE_SID.fullmatch(message_sid):
+        raise click.ClickException("Invalid SMS message SID.")
+    url = f"https://api.twilio.com/2010-04-01/Accounts/{credentials.account_sid}/Messages/{message_sid}.json"
+    try:
+        message = _parse_message(_request_json(http, credentials, url))
+    except (TypeError, ValueError) as exc:
+        raise click.ClickException("Twilio returned an invalid SMS message.") from exc
+    if message.direction != "inbound" or message.recipient != recipient:
+        raise click.ClickException("That SMS message does not belong to the selected agent phone number.")
+    if message.received_at < cutoff:
+        raise click.ClickException("That SMS message is older than the requested --since window.")
+    return message

hound_cli/reports/__init__.py

@@ -0,0 +1 @@
+"""Customer report review commands."""