"""Webhook Action 帮助文档模型。

提供 ``WebhookActionHelp`` 模型，用于描述单个 Webhook Action
的接口文档信息，包括用法说明、payload schema 和 response schema。
"""

from typing import Any

from pydantic import BaseModel, Field


class WebhookActionUsage(BaseModel):
    """Webhook Action 用法说明。

    Parameters
    ----------
    method : str
        HTTP 方法。
    url : str
        请求 URL。
    headers : dict[str, str]
        请求头示例。
    body : dict[str, str]
        请求体示例。
    """

    method: str = Field(..., description="HTTP 方法")
    url: str = Field(..., description="请求 URL")
    headers: dict[str, str] = Field(default_factory=dict, description="请求头示例")
    body: dict[str, str] = Field(default_factory=dict, description="请求体示例")


class WebhookActionHelp(BaseModel):
    """Webhook Action 帮助文档。

    Parameters
    ----------
    action : str
        Action 名称。
    description : str
        Action 描述。
    usage : WebhookActionUsage
        用法说明。
    payload_schema : dict[str, Any]
        Payload 的 JSON Schema。
    response_data_schema : dict[str, Any]
        Response data 的 JSON Schema。

    Examples
    --------
    >>> help_info = WebhookActionHelp(
    ...     action="generate_report_id",
    ...     description="生成报告 ID",
    ...     usage=WebhookActionUsage(
    ...         method="POST",
    ...         url="/api/v1/webhook/",
    ...         headers={},
    ...         body={},
    ...     ),
    ...     payload_schema={"type": "object"},
    ...     response_data_schema={"type": "object"},
    ... )
    >>> help_info.action
    'generate_report_id'
    """

    action: str = Field(..., description="Action 名称")
    description: str = Field(default="", description="Action 描述")
    usage: WebhookActionUsage = Field(..., description="用法说明")
    payload_schema: dict[str, Any] = Field(
        default_factory=dict, description="Payload 的 JSON Schema"
    )
    response_data_schema: dict[str, Any] = Field(
        default_factory=dict,
        description="Response data 的 JSON Schema",
    )
