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

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

topic = SkillTopic(
    name="groups",
    summary="Manage groups and their person/contact membership",
    commands=[
        "turumba groups list",
        "turumba groups get <group-id>",
        "turumba groups create",
        "turumba groups update <group-id>",
        "turumba groups delete <group-id>",
        "turumba groups add-persons <group-id>",
        "turumba groups list-persons <group-id>",
        "turumba groups remove-persons <group-id>",
    ],
    create_params=[
        ParamSpec(
            name="--name / -n",
            type="string",
            required=True,
            description="Group name",
        ),
        ParamSpec(
            name="--description / -d",
            type="string",
            required=False,
            description="Group description",
        ),
        ParamSpec(
            name="--account-id / -a",
            type="UUID",
            required=True,
            description="Account ID. Falls back to config default_account_id",
        ),
        ParamSpec(
            name="--metadata / -m",
            type="JSON string",
            required=False,
            description="Free-form metadata key-value pairs",
            default="{}",
        ),
    ],
    notes=[
        "account_id is REQUIRED by the API. Use --account-id or set default: "
        "turumba config set default_account_id <uuid>",
        "Groups are stored in MongoDB with dynamic metadata.",
        "Groups can contain both persons and contacts as members.",
        "Deleting a group automatically removes all person/contact memberships.",
        "Use add-persons / remove-persons to manage person membership.",
        "Persons can also be assigned to groups at creation time via: "
        "turumba persons create --group-id <gid>",
        "Allowed filters: id (eq, in), name (eq, contains, icontains), "
        "account_id (eq, in), created_at (ge, le, range), updated_at (ge, le, range).",
        "Allowed sorts: name, account_id, created_at, updated_at.",
    ],
    examples=[
        'turumba groups create --name "VIP Customers" --description "High-value customers"',
        'turumba groups create --name "Leads Q1" --metadata \'{"source": "campaign"}\'',
        "turumba groups list -o json",
        "turumba groups list --filter name:contains:VIP",
        "turumba groups get <group-id> -o json",
        'turumba groups update <group-id> --name "Updated Name"',
        "turumba groups add-persons <group-id> --person-id <pid1> --person-id <pid2>",
        "turumba groups list-persons <group-id>",
        "turumba groups remove-persons <group-id> --person-id <pid1> --force",
    ],
    workflows=[
        {
            "name": "Create a group and add persons",
            "steps": [
                'turumba groups create --name "My Group" -o json',
                "turumba persons list -o json",
                "turumba groups add-persons <group-id> --person-id <pid1> --person-id <pid2>",
                "turumba groups list-persons <group-id>",
            ],
        },
        {
            "name": "Send a group message to a group",
            "steps": [
                "turumba groups list -o json",
                "turumba channels list -f channel_type:eq:telegram -o json",
                "turumba group-messages create --group-id <gid> "
                '--channel-id <cid> --body "Hello group!"',
            ],
        },
    ],
    related=["persons", "contacts", "group-messages", "sending"],
)

register_topics(topic)
