"""Slack 厂商专属凭证 Pydantic 模型。

定义两个 ``AuthCredential`` 子类，分别对应 Bot User OAuth Token（``xoxb-``）与
App-Level Token（``xapp-``）两种静态 Token 认证方式。

``oauth2_authorization_code`` 复用框架级 ``OAuth2AuthCodeCredential``，不在本文件定义。

字段与 ``auth_plugins.py`` 中 ``resolve()`` 构造凭证时读取的 ``auth_config`` 字段对齐：
- ``SlackBotTokenCredential`` ↔ ``SlackBotTokenAuthPlugin``
- ``SlackAppTokenCredential`` ↔ ``SlackAppTokenAuthPlugin``

继承关系说明：
- ``SlackBotTokenCredential`` 继承 ``BearerCredential``，以复用 HTTP 执行器
  ``_apply_credential`` 中的 ``isinstance(credential, BearerCredential)`` 分派，
  自动注入 ``Authorization: Bearer {token}`` 头部（参考 Notion
  ``NotionIntegrationTokenCredential`` / HubSpot ``PrivateAppTokenCredential`` 模式）。
- ``SlackAppTokenCredential`` 继承 ``AuthCredential``，仅用于 Socket Mode WebSocket
  握手，不经过 HTTP 执行器，无需 Bearer 头注入。
"""

from __future__ import annotations

from pydantic import ConfigDict, Field

from yuxi.external_systems.framework.auth_plugins.credentials import (
    AuthCredential,
    BearerCredential,
)


class SlackBotTokenCredential(BearerCredential):
    """Slack Bot User OAuth Token 凭证。

    承载 ``xoxb-`` 前缀的 Bot Token，适用于"已通过 Slack App 管理界面手动安装并复制
    Bot Token"的场景。``is_token_based=True`` 但不注册刷新策略（静态 Token），
    与框架级 ``bearer`` 设计一致。

    继承 ``BearerCredential`` 以复用 HTTP 执行器 ``_apply_credential`` 中的
    ``isinstance(credential, BearerCredential)`` 分派，自动注入
    ``Authorization: Bearer {token}`` 头部（参考 Notion
    ``NotionIntegrationTokenCredential`` / HubSpot ``PrivateAppTokenCredential`` 模式）。

    ``scopes`` 字段不参与运行时鉴权（Slack 服务端会校验），仅用于客户端调用前的
    预检与日志展示。
    """

    model_config = ConfigDict(populate_by_name=True, extra="ignore")

    auth_type: str = "slack_bot_token"
    token: str = Field(..., description="Bot User OAuth Token，必须以 xoxb- 开头")
    scopes: list[str] = Field(
        default_factory=list,
        description="Token 已授予的 scope 列表（用于调用前校验）",
    )


class SlackAppTokenCredential(AuthCredential):
    """Slack App-Level Token 凭证（仅 Socket Mode 使用）。

    承载 ``xapp-`` 前缀的 App-Level Token，由 Slack app 设置页生成
    （Settings > Basic Information > App-Level Tokens），必须包含 ``connections:write``
    scope，仅用于 Socket Mode 建立 WebSocket 连接，不直接调用 Web API。

    不继承 ``BearerCredential``：App-Level Token 不经过 HTTP 执行器，无需 Bearer 头注入。
    若误将 ``slack_app_token`` 配置为 HTTP 工具的认证类型，HTTP 执行器
    ``_apply_credential`` 不会注入任何认证头，Slack 将返回 ``not_authed`` 错误，
    此为预期行为（App-Level Token 不应用于 Web API 调用）。
    """

    model_config = ConfigDict(populate_by_name=True, extra="ignore")

    auth_type: str = "slack_app_token"
    token: str = Field(..., description="App-Level Token，必须以 xapp- 开头")
    required_scope: str = Field(
        default="connections:write",
        description="Socket Mode 必备 scope",
    )