"""Skill topic: conversations — complete parameter specs for one-shot agent execution."""

from turumba_cli.skills.registry import ParamSpec, SkillTopic, register_topics

topic = SkillTopic(
    name="conversations",
    summary="Manage conversations (agent-visitor chat threads) with message sub-resource",
    commands=[
        "turumba conversations list",
        "turumba conversations get <conversation-id>",
        "turumba conversations create",
        "turumba conversations update <conversation-id>",
        "turumba conversations delete <conversation-id>",
        "turumba conversations list-messages <conversation-id>",
        "turumba conversations send-message <conversation-id>",
    ],
    create_params=[
        ParamSpec(
            name="--account-id / -a",
            type="UUID",
            required=True,
            description="Account ID. Falls back to config default_account_id",
        ),
        ParamSpec(
            name="--channel-id / -c",
            type="UUID",
            required=False,
            description="Channel ID (exactly one of channel-id or chat-endpoint-id required)",
        ),
        ParamSpec(
            name="--chat-endpoint-id",
            type="UUID",
            required=False,
            description="Chat endpoint ID (exactly one of channel-id or chat-endpoint-id required)",
        ),
        ParamSpec(
            name="--contact-id",
            type="string",
            required=False,
            description="Contact ID (UUID or MongoDB ObjectId)",
        ),
        ParamSpec(
            name="--assignee-id",
            type="UUID",
            required=False,
            description="User ID of assigned agent",
        ),
        ParamSpec(
            name="--team-id",
            type="UUID",
            required=False,
            description="Team ID for team assignment",
        ),
        ParamSpec(
            name="--status",
            type="string",
            required=False,
            description="Conversation status",
            default="open (open | assigned | pending | resolved | closed)",
        ),
        ParamSpec(
            name="--priority",
            type="string",
            required=False,
            description="Conversation priority",
            default="medium (low | medium | high | urgent)",
        ),
        ParamSpec(
            name="--subject / -s",
            type="string",
            required=False,
            description="Conversation subject line",
        ),
        ParamSpec(
            name="--source",
            type="string",
            required=False,
            description="Source identifier (e.g. widget, api, telegram)",
        ),
        ParamSpec(
            name="--metadata / -m",
            type="JSON string",
            required=False,
            description="Custom metadata key-value pairs",
        ),
    ],
    notes=[
        "account_id is REQUIRED. Use --account-id or set default: "
        "turumba config set default_account_id <uuid>",
        "Exactly ONE of --channel-id or --chat-endpoint-id must be provided (XOR constraint).",
        "Status transitions are validated: open->assigned/pending/resolved/closed, "
        "assigned->pending/resolved/closed, pending->assigned/resolved/closed, "
        "resolved->open, closed->open.",
        "send-message creates a message within the conversation thread.",
        "send-message supports --private flag for internal notes not visible to visitors.",
        "Content types for send-message: text, image, file, audio, video.",
        "Filterable fields: id, account_id, channel_id, contact_id, status, priority, "
        "assignee_id, team_id, source, created_at, last_message_at.",
        "Sortable fields: created_at, updated_at, last_message_at, priority, status.",
    ],
    examples=[
        # Create via channel
        "turumba conversations create --channel-id <cid> --contact-id <contact-id> "
        '--subject "Support request"',
        # Create via chat endpoint
        "turumba conversations create --chat-endpoint-id <eid> --contact-id <contact-id>",
        # List open conversations
        "turumba conversations list -f status:eq:open -s last_message_at:desc -o json",
        # List by priority
        "turumba conversations list -f priority:eq:urgent -o json",
        # List unassigned
        "turumba conversations list -f assignee_id:is_null:true -o json",
        # Get details
        "turumba conversations get <conversation-id> -o json",
        # Assign to agent
        "turumba conversations update <conversation-id> --assignee-id <user-id> --status assigned",
        # Resolve
        "turumba conversations update <conversation-id> --status resolved",
        # List messages in conversation
        "turumba conversations list-messages <conversation-id> -s created_at:asc -o json",
        # Send agent reply
        "turumba conversations send-message <conversation-id> --body 'How can I help?'",
        # Send private note
        "turumba conversations send-message <conversation-id> "
        "--body 'Internal note: escalate' --private",
    ],
    workflows=[
        {
            "name": "Handle an incoming conversation",
            "steps": [
                "turumba conversations list -f status:eq:open -s created_at:asc -o json",
                "turumba conversations get <conversation-id> -o json  # review details",
                "turumba conversations update <conversation-id> --assignee-id <my-user-id> "
                "--status assigned",
                "turumba conversations list-messages <conversation-id> -o json  # read history",
                "turumba conversations send-message <conversation-id> --body 'Hi, how can I help?'",
            ],
        },
        {
            "name": "Escalate a conversation to a team",
            "steps": [
                "turumba conversations update <conversation-id> --team-id <team-id> "
                "--priority urgent",
                "turumba conversations send-message <conversation-id> "
                "--body 'Escalating to engineering' --private",
            ],
        },
    ],
    related=["chat-endpoints", "conversation-configs", "messages", "teams"],
)

register_topics(topic)
