guzli-cli 0.2.0__py3-none-any.whl

guzli/commands/conversations.py

@@ -0,0 +1,404 @@
+from __future__ import annotations
+
+import argparse
+from typing import Dict, List, Mapping
+
+from guzli.commands.common import add_json_flag as _add_json_flag
+from guzli.commands.common import parse_bool_flag as _parse_bool_flag
+from guzli.errors import ApiError, ValidationError
+from guzli.models import AgentReplyResult, ConversationDetailView, ConversationSummaryView
+from guzli.runtime import RuntimeContext
+from guzli.types import JsonValue
+from guzli.validators import normalize_list, parse_iso_datetime, parse_json, require_non_empty
+
+
+def handle_conversations_list(context: RuntimeContext, args: argparse.Namespace) -> None:
+    params = build_conversation_list_params(args)
+    payload = context.conversations.list_conversations(params)
+    if args.json:
+        context.renderer.print_json(payload)
+        return
+    items = _extract_items(payload)
+    summaries = [ConversationSummaryView.from_json(item) for item in items]
+    context.renderer.print_conversation_list(summaries)
+    _print_cursor(payload)
+
+
+def handle_conversation_get(context: RuntimeContext, args: argparse.Namespace) -> None:
+    conversation_id = require_non_empty(args.conversation_id, "conversation_id")
+    payload = context.conversations.get_conversation(conversation_id, not args.no_transcript)
+    if args.json:
+        context.renderer.print_json(payload)
+        return
+    if not isinstance(payload, Mapping):
+        raise ApiError("Unexpected response payload")
+    detail = ConversationDetailView.from_json(payload)
+    context.renderer.print_conversation_detail(detail, include_transcript=not args.no_transcript)
+
+
+def handle_conversation_history(context: RuntimeContext, args: argparse.Namespace) -> None:
+    fingerprint_id = require_non_empty(args.fingerprint_id, "fingerprint_id")
+    payload = context.conversations.get_history(fingerprint_id)
+    context.renderer.print_json(payload)
+
+
+def handle_conversation_filters(context: RuntimeContext, args: argparse.Namespace) -> None:
+    payload = context.conversations.get_filters()
+    context.renderer.print_json(payload)
+
+
+def handle_conversation_interactions(context: RuntimeContext, args: argparse.Namespace) -> None:
+    conversation_id = require_non_empty(args.conversation_id, "conversation_id")
+    payload = context.conversations.list_automation_interactions(conversation_id)
+    context.renderer.print_json(payload)
+
+
+def handle_conversation_assign(context: RuntimeContext, args: argparse.Namespace) -> None:
+    conversation_id = require_non_empty(args.conversation_id, "conversation_id")
+    assignment_type = require_non_empty(args.assignment_type, "assignment_type")
+    assigned_to_id = args.assigned_to_id
+    if assignment_type in {"agent", "team"} and not assigned_to_id:
+        raise ValidationError("assigned_to_id is required for agent/team assignments")
+    payload = {
+        "assignment_type": assignment_type,
+        "assigned_to_id": assigned_to_id,
+        "queue_label": args.queue_label,
+        "reason": args.reason,
+    }
+    response = context.conversations.update_assignment(conversation_id, payload)
+    context.renderer.print_json(response)
+
+
+def handle_conversation_mark(context: RuntimeContext, args: argparse.Namespace) -> None:
+    conversation_id = require_non_empty(args.conversation_id, "conversation_id")
+    response = context.conversations.mark_conversation(conversation_id)
+    context.renderer.print_json(response)
+
+
+def handle_conversation_unmark(context: RuntimeContext, args: argparse.Namespace) -> None:
+    conversation_id = require_non_empty(args.conversation_id, "conversation_id")
+    response = context.conversations.unmark_conversation(conversation_id)
+    context.renderer.print_json(response)
+
+
+def handle_conversation_mute(context: RuntimeContext, args: argparse.Namespace) -> None:
+    conversation_id = require_non_empty(args.conversation_id, "conversation_id")
+    mute_expires_at = parse_iso_datetime(args.mute_expires_at, "mute_expires_at")
+    payload = {"mute_expires_at": mute_expires_at} if mute_expires_at else None
+    response = context.conversations.mute_conversation(conversation_id, payload)
+    context.renderer.print_json(response)
+
+
+def handle_conversation_unmute(context: RuntimeContext, args: argparse.Namespace) -> None:
+    conversation_id = require_non_empty(args.conversation_id, "conversation_id")
+    response = context.conversations.unmute_conversation(conversation_id)
+    context.renderer.print_json(response)
+
+
+def handle_conversation_close(context: RuntimeContext, args: argparse.Namespace) -> None:
+    conversation_id = require_non_empty(args.conversation_id, "conversation_id")
+    summary = _resolve_summary(args.summary, args.summary_json)
+    metadata_updates = parse_json(args.metadata_updates, "metadata_updates")
+    payload = {
+        "summary": summary,
+        "duration_seconds": args.duration_seconds,
+        "metadata_updates": metadata_updates or {},
+    }
+    response = context.conversations.close_conversation(conversation_id, payload)
+    context.renderer.print_json(response)
+
+
+def handle_conversation_interaction_state(
+    context: RuntimeContext, args: argparse.Namespace
+) -> None:
+    conversation_id = require_non_empty(args.conversation_id, "conversation_id")
+    state = require_non_empty(args.state, "state")
+    _validate_interaction_state(state)
+    payload = {
+        "state": state,
+        "interaction_id": args.interaction_id,
+        "reason": args.reason,
+    }
+    response = context.conversations.update_interaction_state(conversation_id, payload)
+    context.renderer.print_json(response)
+
+
+def handle_conversation_metrics(context: RuntimeContext, args: argparse.Namespace) -> None:
+    metrics = normalize_list(args.metric)
+    params: Dict[str, object] = {"hours": args.hours}
+    if metrics:
+        params["metric"] = metrics
+    if args.metric_agent_id:
+        params["agent_id"] = args.metric_agent_id
+    if args.metric_channel:
+        params["channel"] = args.metric_channel
+    payload = context.conversations.get_metrics(params)
+    context.renderer.print_json(payload)
+
+
+def handle_agent_reply(context: RuntimeContext, args: argparse.Namespace) -> None:
+    conversation_id = require_non_empty(args.conversation_id, "conversation_id")
+    message = require_non_empty(args.message, "message")
+    if len(message) > 4000:
+        raise ValidationError("message exceeds 4000 characters")
+    metadata = parse_json(args.metadata, "metadata") or {}
+    payload = {"message": message, "metadata": metadata}
+    response = context.replies.send_agent_reply(conversation_id, payload)
+    if args.json:
+        context.renderer.print_json(response)
+        return
+    if not isinstance(response, Mapping):
+        raise ApiError("Unexpected response payload")
+    result = AgentReplyResult.from_json(response)
+    context.renderer.print_reply_result(result)
+
+
+def build_conversation_list_params(args: argparse.Namespace) -> Dict[str, object]:
+    params: Dict[str, object] = {}
+    status = normalize_list(args.status)
+    channel = normalize_list(args.channel)
+    tags = normalize_list(args.tags)
+    platform = normalize_list(args.platform)
+    priority = normalize_list(args.priority)
+    assignment_type = normalize_list(args.assignment_type)
+    sentiment = normalize_list(args.sentiment)
+    interaction_state = normalize_list(args.interaction_state)
+    if status:
+        params["status"] = status
+    if channel:
+        params["channel"] = channel
+    if tags:
+        params["tags"] = tags
+    if platform:
+        params["platform"] = platform
+    if args.since:
+        params["since"] = parse_iso_datetime(args.since, "since")
+    if args.limit:
+        params["limit"] = args.limit
+    if args.cursor:
+        params["cursor"] = args.cursor
+    if args.sort_by:
+        params["sort_by"] = args.sort_by
+    if args.sort_order:
+        params["sort_order"] = args.sort_order
+    if assignment_type:
+        params["assignment_type"] = assignment_type
+    if args.assigned_to_id:
+        params["assigned_to_id"] = args.assigned_to_id
+    if args.assigned_to_type:
+        params["assigned_to_type"] = args.assigned_to_type
+    if priority:
+        params["priority"] = priority
+    if args.is_marked is not None:
+        params["is_marked"] = args.is_marked
+    if args.is_muted is not None:
+        params["is_muted"] = args.is_muted
+    if sentiment:
+        params["sentiment"] = sentiment
+    if interaction_state:
+        params["interaction_state"] = interaction_state
+    if args.has_unread is not None:
+        params["has_unread"] = args.has_unread
+    if args.unread_participant_type:
+        params["unread_participant_type"] = args.unread_participant_type
+    if args.fingerprint_id:
+        params["fingerprint_id"] = args.fingerprint_id
+    if args.pane_assignee_id:
+        params["pane_assignee_id"] = args.pane_assignee_id
+    if args.view_id:
+        params["view_id"] = args.view_id
+    if args.queue_label:
+        params["queue_label"] = args.queue_label
+    return params
+
+
+def _resolve_summary(summary_text: str | None, summary_json: str | None) -> JsonValue | None:
+    if summary_text and summary_json:
+        raise ValidationError("Provide either summary or summary_json, not both")
+    if summary_json:
+        summary = parse_json(summary_json, "summary_json")
+        if not isinstance(summary, Mapping):
+            raise ValidationError("summary_json must be an object")
+        return summary
+    if summary_text:
+        return summary_text.strip() or None
+    return None
+
+
+def _validate_interaction_state(value: str) -> None:
+    allowed = {
+        "none",
+        "awaiting_visitor",
+        "awaiting_agent",
+        "awaiting_tool",
+        "completed",
+        "cancelled",
+        "timed_out",
+    }
+    if value.strip().lower() not in allowed:
+        raise ValidationError(f"Invalid interaction state: {value}")
+
+
+def _extract_items(payload: JsonValue) -> List[Mapping[str, JsonValue]]:
+    if not isinstance(payload, Mapping):
+        raise ApiError("Unexpected response payload")
+    items = payload.get("items")
+    if not isinstance(items, list):
+        return []
+    return [item for item in items if isinstance(item, Mapping)]
+
+
+def _print_cursor(payload: JsonValue) -> None:
+    if not isinstance(payload, Mapping):
+        return
+    next_cursor = payload.get("nextCursor") or payload.get("next_cursor")
+    if isinstance(next_cursor, str) and next_cursor:
+        print(f"Next cursor: {next_cursor}")
+
+
+def _add_conversations_list(conv_sub: argparse._SubParsersAction) -> None:
+    parser = conv_sub.add_parser("list", help="List conversations")
+    parser.add_argument("--status", action="append")
+    parser.add_argument("--channel", action="append")
+    parser.add_argument("--tags", action="append")
+    parser.add_argument("--platform", action="append")
+    parser.add_argument("--since")
+    parser.add_argument("--limit", type=int)
+    parser.add_argument("--cursor")
+    parser.add_argument("--sort-by", dest="sort_by")
+    parser.add_argument("--sort-order", dest="sort_order")
+    parser.add_argument("--assignment-type", dest="assignment_type", action="append")
+    parser.add_argument("--assigned-to-id", dest="assigned_to_id")
+    parser.add_argument("--assigned-to-type", dest="assigned_to_type")
+    parser.add_argument("--priority", action="append")
+    parser.add_argument("--sentiment", action="append")
+    parser.add_argument("--is-marked", dest="is_marked", type=_parse_bool_flag)
+    parser.add_argument("--is-muted", dest="is_muted", type=_parse_bool_flag)
+    parser.add_argument("--interaction-state", dest="interaction_state", action="append")
+    parser.add_argument("--has-unread", dest="has_unread", type=_parse_bool_flag)
+    parser.add_argument("--unread-participant-type", dest="unread_participant_type")
+    parser.add_argument("--fingerprint-id", dest="fingerprint_id")
+    parser.add_argument("--pane-assignee-id", dest="pane_assignee_id")
+    parser.add_argument("--view-id", dest="view_id")
+    parser.add_argument("--queue-label", dest="queue_label")
+    _add_json_flag(parser)
+    parser.set_defaults(handler=handle_conversations_list)
+
+
+def _add_conversation_get(conv_sub: argparse._SubParsersAction) -> None:
+    parser = conv_sub.add_parser("get", help="Get conversation details")
+    parser.add_argument("conversation_id")
+    parser.add_argument("--no-transcript", action="store_true")
+    _add_json_flag(parser)
+    parser.set_defaults(handler=handle_conversation_get)
+
+
+def _add_conversation_history(conv_sub: argparse._SubParsersAction) -> None:
+    parser = conv_sub.add_parser("history", help="Get conversation history by fingerprint")
+    parser.add_argument("fingerprint_id")
+    parser.set_defaults(handler=handle_conversation_history)
+
+
+def _add_conversation_filters(conv_sub: argparse._SubParsersAction) -> None:
+    parser = conv_sub.add_parser("filters", help="List available conversation filters")
+    parser.set_defaults(handler=handle_conversation_filters)
+
+
+def _add_conversation_interactions(conv_sub: argparse._SubParsersAction) -> None:
+    parser = conv_sub.add_parser("automation-interactions", help="List automation interactions")
+    parser.add_argument("conversation_id")
+    parser.set_defaults(handler=handle_conversation_interactions)
+
+
+def _add_conversation_assign(conv_sub: argparse._SubParsersAction) -> None:
+    parser = conv_sub.add_parser("assign", help="Assign conversation")
+    parser.add_argument("conversation_id")
+    parser.add_argument("--assignment-type", dest="assignment_type", required=True)
+    parser.add_argument("--assigned-to-id", dest="assigned_to_id")
+    parser.add_argument("--queue-label", dest="queue_label")
+    parser.add_argument("--reason")
+    parser.set_defaults(handler=handle_conversation_assign)
+
+
+def _add_conversation_mark(conv_sub: argparse._SubParsersAction) -> None:
+    parser = conv_sub.add_parser("mark", help="Mark conversation")
+    parser.add_argument("conversation_id")
+    parser.set_defaults(handler=handle_conversation_mark)
+
+
+def _add_conversation_unmark(conv_sub: argparse._SubParsersAction) -> None:
+    parser = conv_sub.add_parser("unmark", help="Unmark conversation")
+    parser.add_argument("conversation_id")
+    parser.set_defaults(handler=handle_conversation_unmark)
+
+
+def _add_conversation_mute(conv_sub: argparse._SubParsersAction) -> None:
+    parser = conv_sub.add_parser("mute", help="Mute conversation")
+    parser.add_argument("conversation_id")
+    parser.add_argument("--mute-expires-at", dest="mute_expires_at")
+    parser.set_defaults(handler=handle_conversation_mute)
+
+
+def _add_conversation_unmute(conv_sub: argparse._SubParsersAction) -> None:
+    parser = conv_sub.add_parser("unmute", help="Unmute conversation")
+    parser.add_argument("conversation_id")
+    parser.set_defaults(handler=handle_conversation_unmute)
+
+
+def _add_conversation_close(conv_sub: argparse._SubParsersAction) -> None:
+    parser = conv_sub.add_parser("close", help="Close conversation")
+    parser.add_argument("conversation_id")
+    parser.add_argument("--summary")
+    parser.add_argument("--summary-json", dest="summary_json")
+    parser.add_argument("--duration-seconds", dest="duration_seconds", type=int)
+    parser.add_argument("--metadata-updates", dest="metadata_updates")
+    parser.set_defaults(handler=handle_conversation_close)
+
+
+def _add_conversation_interaction_state(conv_sub: argparse._SubParsersAction) -> None:
+    parser = conv_sub.add_parser("interaction-state", help="Update interaction state")
+    parser.add_argument("conversation_id")
+    parser.add_argument("--state", required=True)
+    parser.add_argument("--interaction-id", dest="interaction_id")
+    parser.add_argument("--reason")
+    parser.set_defaults(handler=handle_conversation_interaction_state)
+
+
+def _add_conversation_metrics(conv_sub: argparse._SubParsersAction) -> None:
+    parser = conv_sub.add_parser("metrics", help="Fetch conversation metrics")
+    parser.add_argument("--hours", type=int, default=24)
+    parser.add_argument("--metric", action="append")
+    parser.add_argument("--agent-id", dest="metric_agent_id")
+    parser.add_argument("--channel", dest="metric_channel")
+    parser.set_defaults(handler=handle_conversation_metrics)
+
+
+def _add_agent_reply(replies_sub: argparse._SubParsersAction) -> None:
+    parser = replies_sub.add_parser("send", help="Send agent reply")
+    parser.add_argument("conversation_id")
+    parser.add_argument("message")
+    parser.add_argument("--metadata")
+    _add_json_flag(parser)
+    parser.set_defaults(handler=handle_agent_reply)
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    conversations = subparsers.add_parser("conversations", help="Conversation operations")
+    conv_sub = conversations.add_subparsers(dest="conversations_command", required=True)
+    _add_conversations_list(conv_sub)
+    _add_conversation_get(conv_sub)
+    _add_conversation_history(conv_sub)
+    _add_conversation_filters(conv_sub)
+    _add_conversation_interactions(conv_sub)
+    _add_conversation_assign(conv_sub)
+    _add_conversation_mark(conv_sub)
+    _add_conversation_unmark(conv_sub)
+    _add_conversation_mute(conv_sub)
+    _add_conversation_unmute(conv_sub)
+    _add_conversation_close(conv_sub)
+    _add_conversation_interaction_state(conv_sub)
+    _add_conversation_metrics(conv_sub)
+
+    replies = subparsers.add_parser("agent-replies", help="Send agent replies")
+    replies_sub = replies.add_subparsers(dest="replies_command", required=True)
+    _add_agent_reply(replies_sub)

guzli/commands/integrations.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import argparse
+from typing import Dict
+
+from guzli.errors import ConfigError
+from guzli.runtime import RuntimeContext
+from guzli.validators import require_non_empty
+
+
+def handle_integrations_connect_twilio(context: RuntimeContext, args: argparse.Namespace) -> None:
+    organization_id = (
+        getattr(args, "organization_id", None) or context.organization_id or ""
+    ).strip()
+    if not organization_id:
+        raise ConfigError(
+            "organization_id is required — set it via `guzli auth login --organization-id …`."
+        )
+    body: Dict[str, object] = {
+        "account_sid": require_non_empty(args.account_sid, "account_sid"),
+        "auth_token": require_non_empty(args.auth_token, "auth_token"),
+    }
+    if args.label:
+        body["label"] = args.label
+    if args.agent_id:
+        body["agent_id"] = args.agent_id
+    payload = context.integrations.connect_twilio(organization_id, body)
+    context.renderer.print_json(payload)
+
+
+def _add_integrations_connect_twilio(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser(
+        "connect-twilio",
+        help="Connect a Twilio integration (creates the telephony account Campaign Launch needs)",
+    )
+    parser.add_argument(
+        "--account-sid", dest="account_sid", required=True, help="Twilio Account SID (AC…)"
+    )
+    parser.add_argument("--auth-token", dest="auth_token", required=True, help="Twilio auth token")
+    parser.add_argument("--label", help="Optional display label for the account")
+    parser.add_argument("--agent-id", dest="agent_id", help="Optional agent binding")
+    parser.set_defaults(handler=handle_integrations_connect_twilio)
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    integrations = subparsers.add_parser("integrations", help="Connect external integrations")
+    integ_sub = integrations.add_subparsers(dest="integrations_command", required=True)
+    _add_integrations_connect_twilio(integ_sub)