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

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

topic = SkillTopic(
    name="messages",
    summary="Manage individual messages (outbound, inbound, system) with delivery tracking",
    commands=[
        "turumba messages list",
        "turumba messages get <message-id>",
        "turumba messages create",
        "turumba messages update <message-id>",
        "turumba messages delete <message-id>",
    ],
    create_params=[
        ParamSpec(
            name="--body / -b",
            type="string",
            required=True,
            description="Message body text",
        ),
        ParamSpec(
            name="--direction / -d",
            type="string",
            required=False,
            description="Message direction",
            default="outbound (outbound | inbound | system)",
        ),
        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="Delivery channel ID. Required for outbound dispatch",
        ),
        ParamSpec(
            name="--delivery-address",
            type="string",
            required=False,
            description="Recipient address (phone number, chat ID, email, etc.)",
        ),
        ParamSpec(
            name="--contact-id",
            type="string",
            required=False,
            description="Contact ID (UUID or MongoDB ObjectId)",
        ),
        ParamSpec(
            name="--template-id",
            type="UUID",
            required=False,
            description="Template ID used to render the message body",
        ),
        ParamSpec(
            name="--scheduled-at",
            type="ISO 8601 datetime",
            required=False,
            description="Schedule message for future delivery",
        ),
        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>",
        "For outbound messages, provide --channel-id and --delivery-address for dispatch.",
        "Direct outbound messages (no group/scheduled parent) are auto-published to "
        "the dispatch pipeline for immediate delivery.",
        "Update only supports status tracking fields: --status, --sent-at, "
        "--delivered-at, --failed-at, --error-details, --metadata.",
        "Status values: queued, sending, sent, delivered, failed, permanently_failed, scheduled.",
        "Filterable fields: id, account_id, channel_id, contact_id, direction, status, "
        "delivery_address, template_id, group_message_id, scheduled_message_id, "
        "sent_by_user_id, conversation_id, chat_endpoint_id, content_type, is_private, "
        "sender_type, sender_id, scheduled_at, sent_at, delivered_at, created_at, updated_at.",
        "Sortable fields: status, scheduled_at, sent_at, delivered_at, created_at, updated_at.",
        "For bulk sending, use group-messages instead. For recurring, use scheduled-messages.",
    ],
    examples=[
        # Send a direct outbound message
        "turumba messages create --body 'Hello!' --channel-id <cid> "
        "--delivery-address '+251911123456'",
        # With template
        "turumba messages create --body 'Rendered text' --template-id <tid> "
        "--channel-id <cid> --delivery-address '123456'",
        # List by status
        "turumba messages list -f status:eq:failed -o json",
        # List by channel
        "turumba messages list -f channel_id:eq:<cid> -s created_at:desc",
        # List by direction
        "turumba messages list -f direction:eq:inbound -o json",
        # List by conversation
        "turumba messages list -f conversation_id:eq:<conv-id> -s created_at:asc",
        # Get details
        "turumba messages get <message-id> -o json",
        # Update status
        "turumba messages update <message-id> --status delivered "
        "--delivered-at 2026-03-26T10:00:00Z",
    ],
    workflows=[
        {
            "name": "Send a direct message via channel",
            "steps": [
                "turumba channels list -f channel_type:eq:telegram -o json  # find channel",
                "turumba messages create --body 'Hello!' --channel-id <cid> "
                "--delivery-address '123456' -o json",
                "turumba messages get <message-id> -o json  # check delivery status",
            ],
        },
        {
            "name": "Investigate failed messages",
            "steps": [
                "turumba messages list -f status:eq:failed -s created_at:desc -o json",
                "turumba messages get <message-id> -o json  # check error_details",
            ],
        },
    ],
    related=["channels", "group-messages", "scheduled-messages", "templates", "sending"],
)

register_topics(topic)
