"""Twilio 厂商集成元数据。

定义 ``IntegrationMetadata(key="twilio", ...)``，由 ``__init__.py`` 自注册到
``IntegrationRegistry``。元数据为内存态，不持久化到数据库。

同时定义 API 版本常量、API 根路径、核心资源路径模板与健康检查路径，
供 ``operations.py`` / ``generators.py`` 复用。
"""

from __future__ import annotations

from yuxi.external_systems.integrations.schemas import IntegrationMetadata

# Account API 长期稳定版本
DEFAULT_API_VERSION = "2010-04-01"
# API 根路径（不含尾部斜杠，与 HttpAdapterConfig.base_url 拼接约定一致）
DEFAULT_BASE_URL = "https://api.twilio.com"
# 健康检查路径模板（{AccountSid} 由 use_cases 层填充）
HEALTH_CHECK_PATH = "/2010-04-01/Accounts/{AccountSid}.json"

# 核心资源路径模板（相对路径，base_url 由 adapter_config.base_url 提供）
# {AccountSid} 在生成期烘焙到 path_template（见设计文档 §3.5）
RESOURCE_PATHS = {
    "Messages": "/2010-04-01/Accounts/{AccountSid}/Messages.json",
    "Calls": "/2010-04-01/Accounts/{AccountSid}/Calls.json",
    "IncomingPhoneNumbers": "/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers.json",
    "AvailablePhoneNumbers": "/2010-04-01/Accounts/{AccountSid}/AvailablePhoneNumbers/{CountryCode}/Local.json",
    "UsageRecords": "/2010-04-01/Accounts/{AccountSid}/Usage/Records.json",
    "Accounts": "/2010-04-01/Accounts/{AccountSid}.json",
}

TWILIO_METADATA = IntegrationMetadata(
    key="twilio",
    display_name="Twilio",
    description="Twilio 通信集成，支持短信、语音、号码管理与 Webhook 验签",
    adapter_type="http",
    source_types=["twilio"],
    supported_auth_types=["basic", "api_key", "twilio_hmac"],
    tags=["Communication", "SMS", "Voice", "Telecom"],
    icon="twilio",
    docs_url="https://www.twilio.com/docs/usage/api",
    # connection_extra_schema 遵循 JSON Schema 格式（与 dynamics365 一致），
    # 描述 connection_config 除 base_url 外的额外字段。
    connection_extra_schema={
        "type": "object",
        "properties": {
            "account_sid": {
                "type": "string",
                "pattern": "^AC[0-9a-f]{32}$",
                "description": "Twilio Account SID（AC 开头，32 位十六进制）",
            },
            "api_version": {
                "type": "string",
                "default": "2010-04-01",
                "description": "API 版本（Account API 长期稳定）",
            },
            "webhook_url": {
                "type": "string",
                "description": ("Webhook 完整 URL（启用 twilio_hmac 验签时必填，须与 Twilio 控制台配置完全一致）"),
            },
            "region": {
                "type": "string",
                "description": "Twilio 区域（如 us1 / ie1）",
            },
            "edge": {
                "type": "string",
                "description": "Twilio 边缘节点（如 sydney）",
            },
        },
        "required": ["account_sid"],
    },
    # example_config 仅包含 connection_config 字段（auth_config 由 auth_type + auth_config 单独管理）
    example_config={
        "account_sid": "AC" + "a" * 30,
        "base_url": "https://api.twilio.com",
        "api_version": "2010-04-01",
    },
    dependency_note=(
        "出站 API 请求使用 basic 认证（Account SID + Auth Token），复用框架插件。"
        "入站 Webhook 验签使用 twilio_hmac 认证（新增专属插件，仅承载凭证模型，"
        "验签逻辑在 operations.py 实现）。"
        "Auth Token 长期有效，无需自动刷新；管理员轮换 Token 后需更新连接配置。"
        "短信/语音按条计费，调用前需确认目标国家合规要求与费用预算。"
        "Messaging Service 批量发送待 P3 阶段评估。"
    ),
)