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

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

topic = SkillTopic(
    name="persons",
    summary="Manage persons (recipients with dynamic properties and group membership)",
    commands=[
        "turumba persons list",
        "turumba persons get <person-id>",
        "turumba persons create",
        "turumba persons update <person-id>",
        "turumba persons delete <person-id>",
    ],
    create_params=[
        ParamSpec(
            name="--account-id / -a",
            type="UUID",
            required=True,
            description="Account ID. Falls back to config default_account_id",
        ),
        ParamSpec(
            name="--properties / -p",
            type="JSON string",
            required=False,
            description="Dynamic key-value properties (e.g. name, phone, email, telegram_chat_id)",
            default="{}",
        ),
        ParamSpec(
            name="--group-id",
            type="string (repeatable)",
            required=False,
            description="Group ID(s) to assign this person to. Repeat for multiple groups",
        ),
    ],
    notes=[
        "account_id is REQUIRED by the API. Use --account-id or set default: "
        "turumba config set default_account_id <uuid>",
        "Properties are free-form key-value pairs. Common fields: name, phone, "
        "email, telegram_chat_id, address, notes.",
        "A person can belong to multiple groups. Use --group-id multiple times.",
        "Persons are stored in MongoDB with dynamic properties.",
    ],
    examples=[
        # One-shot with account_id
        "turumba persons create --account-id 66a08c9b-c8de-46bb-989e-5b96062c2510 "
        '--properties \'{"name": "Abebe Kebede", "phone": "+251911123456"}\'',
        # Using default account_id from config
        'turumba persons create --properties \'{"name": "Abebe", '
        '"phone": "+251911123456", "telegram_chat_id": "1003774364"}\'',
        # With group assignment
        'turumba persons create --properties \'{"name": "Abebe"}\' '
        "--group-id <group-id-1> --group-id <group-id-2>",
        # List & filter
        "turumba persons list -o json",
        "turumba persons get <person-id> -o json",
        # Update (merge properties)
        'turumba persons update <person-id> --properties \'{"email": "a@b.com"}\'',
        # Update (replace all properties)
        'turumba persons update <person-id> --properties \'{"phone": "+251911..."}\' --replace',
    ],
    workflows=[
        {
            "name": "Create a person and add to a group",
            "steps": [
                "turumba config set default_account_id <your-account-id>  # one-time setup",
                "turumba groups list -o json  # find group IDs",
                'turumba persons create --properties \'{"name": "Abebe", '
                '"phone": "+251911123456"}\' --group-id <gid> -o json',
            ],
        },
        {
            "name": "Create person and send group message",
            "steps": [
                'turumba persons create --properties \'{"name": "Abebe", '
                '"phone": "+251911..."}\' --group-id <gid> -o json',
                "turumba channels list -f channel_type:eq:telegram -o json",
                "turumba group-messages create --group-id <gid> "
                '--channel-id <cid> --body "Welcome!"',
            ],
        },
    ],
    related=["contacts", "sending", "group-messages"],
)

register_topics(topic)
