# retoor <retoor@molodetz.nl>

from __future__ import annotations

from ..actions.spec import Action, Param


def arg(
    name: str, description: str, required: bool = False, kind: str = "string"
) -> Param:
    return Param(
        name=name,
        location="body",
        description=description,
        required=required,
        type=kind,
    )


UI = (
    "Presents a channel-aware interactive prompt (CA-IWP). The host renders the best "
    "affordance for the current channel (site custom elements, Telegram inline keys, or "
    "plain numbered menus). Blocks until the user submits, cancels, or the timeout fires. "
    "Never invent HTML or custom-element tags in your prose - call this tool instead."
)

INTERACTION_ACTIONS: tuple[Action, ...] = (
    Action(
        name="ui_prompt",
        method="LOCAL",
        path="",
        summary="Ask the user an interactive question with widgets (confirm, choice, text, form)",
        description=(
            UI
            + " Prefer this for decisions and short forms. Returns structured "
            "{interaction_id, status, values, meta}. Branch on status: submitted, cancelled, "
            "timeout, superseded, or error. Keep labels short and value tokens stable."
        ),
        handler="interaction",
        requires_auth=False,
        params=(
            arg("title", "Short question title (≤120 chars).", required=True),
            arg("description", "Optional help prose (≤500 chars)."),
            arg(
                "widgets",
                "Ordered list of widget objects. Types: confirm, choice, choice_multi, "
                "text, number, date, select, // (help), group. Each input needs name+label; "
                "choice types need options[{value,label}].",
                required=True,
                kind="array",
            ),
            arg("submit_label", "Primary action label (default Confirm)."),
            arg("cancel_label", "Cancel action label (default Cancel)."),
            arg("cancelable", "Whether the user may cancel (default true).", kind="boolean"),
            arg(
                "timeout_sec",
                "Optional timeout in seconds (0 = none, max 86400).",
                kind="integer",
            ),
            arg("id", "Optional stable interaction id (a-z, digits, hyphens)."),
        ),
    ),
    Action(
        name="ui_cancel",
        method="LOCAL",
        path="",
        summary="Cancel the open interactive prompt",
        description="Closes the current open interaction (or the one named by id) with status cancelled.",
        handler="interaction",
        requires_auth=False,
        params=(
            arg("id", "Optional interaction id to cancel; defaults to the open one."),
            arg("reason", "Optional cancel reason."),
        ),
    ),
    Action(
        name="ui_notify",
        method="LOCAL",
        path="",
        summary="Show a non-blocking ephemeral status on channels that support it",
        description=(
            "Sends a short status line to the user without waiting. Only effective when the "
            "channel advertises ephemeral_status (site-chat). Elsewhere it is skipped."
        ),
        handler="interaction",
        requires_auth=False,
        params=(arg("text", "Status text to show (≤200 chars).", required=True),),
    ),
    Action(
        name="interactions_get",
        method="LOCAL",
        path="",
        summary="Show whether interactive widgets (ui_prompt) are enabled for the user",
        description=(
            "Returns the effective interactive-widgets preference: enabled (bool), source "
            "('user' override or 'default'), the admin default, and the user's override if set. "
            "The site default is set by administrators on the Devii service; users may override "
            "it on their profile or with interactions_set."
        ),
        handler="interaction",
        requires_auth=True,
        read_only=True,
    ),
    Action(
        name="interactions_set",
        method="LOCAL",
        path="",
        summary="Enable, disable, or reset interactive widgets for the user",
        description=(
            "Sets whether this account accepts interactive ui_prompt widgets. Pass enabled=true "
            "or false to override the admin default; pass reset=true (or omit enabled and set "
            "reset) to clear the override and inherit the admin default again. Guests cannot "
            "set a preference."
        ),
        handler="interaction",
        requires_auth=True,
        params=(
            arg(
                "enabled",
                "true to enable interactive widgets, false to disable them. Omit when reset=true.",
                kind="boolean",
            ),
            arg(
                "reset",
                "true to clear the user override and inherit the administrator default again.",
                kind="boolean",
            ),
        ),
    ),
)
