"""Microsoft Teams User-Agent 构建模块。

为 Graph API 和 Bot Framework 请求构建标准 User-Agent 头，
便于追踪和问题排查。
"""

from __future__ import annotations

import platform

_USER_AGENT_PRODUCT = "ForcePilot-MSTeams"
_USER_AGENT_VERSION = "1.0.0"

_DEFAULT_USER_AGENT = (
    f"{_USER_AGENT_PRODUCT}/{_USER_AGENT_VERSION}"
    f" ({platform.system()} {platform.release()}; Python {platform.python_version()})"
)

_HEADER_NAME = "User-Agent"


def build_user_agent(
    product: str = _USER_AGENT_PRODUCT,
    version: str = _USER_AGENT_VERSION,
    extra: str | None = None,
) -> str:
    parts = [f"{product}/{version}"]
    parts.append(f"({platform.system()} {platform.release()}; Python {platform.python_version()})")
    if extra:
        parts.append(extra)
    return " ".join(parts)


def ensure_user_agent(headers: dict[str, str] | None = None, extra: str | None = None) -> dict[str, str]:
    result = dict(headers or {})

    result.setdefault(_HEADER_NAME, build_user_agent(extra=extra))
    return result


def get_default_user_agent() -> str:
    return _DEFAULT_USER_AGENT