"""飞书 API HTTP 客户端。 通过 httpx.AsyncClient 调用飞书开放平台 API，封装 tenant_access_token 管理、通用请求与 IM / 通讯录 / OAuth API。HTTP 异常与飞书业务错误码 通过 error_translator 转换为契约层异常，不向外抛原生异常。token 通过 CachePort 缓存（key 为 feishu:token:{app_id}，TTL=expires_in-60s）， 客户端本身不持有 mutable 状态。 连接池由 lifecycle 统一管理（onInit 创建 / onUnload 关闭），通过 ``attach_http_client`` 注入；未注入时降级为每请求独立 client（兼容 测试与未启用 lifecycle 的场景）。 依赖方向：仅 import yuxi.channels.contract.* 与标准库 / httpx，不污染 框架层。error_translator 为本插件内部模块（任务 2 产出）。 """ from __future__ import annotations import json import time from typing import Any import httpx from yuxi.channels.contract.dtos.config import ConfigScope from yuxi.channels.contract.errors import DependencyError from yuxi.channels.contract.ports.driven.cache_port import CachePort from yuxi.channels.contract.ports.driven.config_port import ConfigPort from yuxi.channels.contract.ports.driven.logger_port import LoggerPort from . import error_translator from ._constants import CHANNEL_TARGET _TOKEN_CACHE_KEY_PREFIX = "feishu:token:" _APP_TOKEN_CACHE_KEY_PREFIX = "feishu:app_token:" _TOKEN_REFRESH_LEAD_TIME_SEC = 60 class FeishuClient: """飞书 API HTTP 客户端。 通过 DI 接收 ConfigPort / CachePort / LoggerPort，不访问全局 settings 或 logger。token 通过 CachePort 缓存，客户端不持有 mutable 状态。所有 方法为 async，HTTP 异常通过 error_translator.wrap_http_exception 转换， 飞书业务错误码非 0 通过 error_translator.translate_feishu_error 转换。 连接池由 lifecycle 统一管理（onInit 创建 / onUnload 关闭），通过 ``attach_http_client`` 注入；未注入时降级为每请求独立 client（兼容 测试与未启用 lifecycle 的场景）。 """ def __init__( self, config_port: ConfigPort, cache_port: CachePort, logger_port: LoggerPort, ) -> None: self._config = config_port self._cache = cache_port self._logger = logger_port # 由 lifecycle 注入的共享连接池；为 None 时降级为每请求独立 client self._http_client: httpx.AsyncClient | None = None # ------------------------------------------------------------------ # 连接池管理 # ------------------------------------------------------------------ def attach_http_client(self, client: httpx.AsyncClient) -> None: """注入 lifecycle 管理的共享 httpx 连接池。 由 ``FeishuLifecycleHandler.onInit`` 调用，将创建好的连接池注入 客户端；``onUnload`` 关闭前由 lifecycle 置空以避免悬挂引用。 @consistency - 幂等：重复调用以最后一次注入的 client 为准 """ self._http_client = client def detach_http_client(self) -> None: """解除共享连接池引用（由 lifecycle 在 onUnload 关闭前调用）。 @consistency - 幂等：重复调用安全 """ self._http_client = None # ------------------------------------------------------------------ # 内部辅助 # ------------------------------------------------------------------ async def _get_account_config(self, account_id: str) -> dict[str, Any]: """读取账户级配置（app_id / app_secret）。""" cv_app_id = await self._config.get( "app_id", scope=ConfigScope.ACCOUNT, target=account_id, ) cv_app_secret = await self._config.get( "app_secret", scope=ConfigScope.ACCOUNT, target=account_id, ) return { "app_id": cv_app_id.value, "app_secret": cv_app_secret.value, } async def _get_channel_config(self, key: str) -> Any: """读取渠道级配置（api_base_url / request_timeout_ms）。""" cv = await self._config.get( key, scope=ConfigScope.CHANNEL, target=CHANNEL_TARGET, ) return cv.value async def _get_request_timeout_seconds(self) -> float: """从配置读取请求超时（秒）。""" timeout_ms = await self._get_channel_config("request_timeout_ms") return float(timeout_ms) / 1000.0 def _token_cache_key(self, app_id: str) -> str: return f"{_TOKEN_CACHE_KEY_PREFIX}{app_id}" async def _get_token_for_account(self, account_id: str) -> str: """获取账户的 tenant_access_token。""" account_config = await self._get_account_config(account_id) token, _ = await self.get_tenant_access_token( account_config["app_id"], account_config["app_secret"], ) return token async def _build_auth_header(self, account_id: str) -> dict[str, str]: """获取账户 token 并构造 Authorization 头。""" token = await self._get_token_for_account(account_id) return {"Authorization": f"Bearer {token}"} async def _execute_http( self, method: str, url: str, headers: dict[str, str], *, json_body: dict | None = None, params: dict | None = None, data: dict | None = None, files: dict | None = None, ) -> httpx.Response: """执行 HTTP 请求，HTTP 异常转换为契约异常。 不负责 token 注入与业务错误码校验，由调用方处理。优先复用 lifecycle 注入的共享连接池；未注入时降级为每请求独立 ``httpx.AsyncClient`` （兼容测试与未启用 lifecycle 的场景）。HTTP 异常经 ``error_translator.wrap_http_exception`` 转换，并传入实际配置 的 ``timeout_ms`` 保证 ``TimeoutError`` 携带准确超时值。 """ timeout = await self._get_request_timeout_seconds() try: if self._http_client is not None: resp = await self._http_client.request( method, url, json=json_body, params=params, data=data, files=files, headers=headers, timeout=timeout, ) else: # 连接池未注入时降级为每请求独立 client（兼容测试场景） async with httpx.AsyncClient(timeout=timeout) as client: resp = await client.request( method, url, json=json_body, params=params, data=data, files=files, headers=headers, ) resp.raise_for_status() except httpx.HTTPError as exc: await self._logger.exception( "Feishu HTTP request failed", exc_info=exc, method=method, url=url, ) raise error_translator.wrap_http_exception( exc, timeout_ms=int(timeout * 1000), ) from exc return resp @staticmethod def _parse_json_response(resp: httpx.Response) -> dict: """解析 JSON 响应，校验飞书业务错误码。 code 非 0 时通过 error_translator.translate_feishu_error 转换为 契约异常。code 为 0 时返回完整响应字典。 """ data = resp.json() code = data.get("code", 0) if code != 0: raise error_translator.translate_feishu_error( code, data.get("msg", ""), ) from None return data async def _request_json( self, method: str, path: str, account_id: str, *, json_body: dict | None = None, params: dict | None = None, data: dict | None = None, files: dict | None = None, ) -> dict: """发起带 tenant token 的请求并返回校验后的 JSON。""" headers = await self._build_auth_header(account_id) api_base_url = await self._get_channel_config("api_base_url") url = f"{api_base_url}{path}" resp = await self._execute_http( method, url, headers, json_body=json_body, params=params, data=data, files=files, ) return self._parse_json_response(resp) # ------------------------------------------------------------------ # Token 管理 # ------------------------------------------------------------------ async def get_tenant_access_token( self, app_id: str, app_secret: str, ) -> tuple[str, int]: """获取 tenant_access_token，缓存命中返回剩余 TTL。 缓存写入时存储绝对过期时间戳 ``expires_at``，缓存命中时根据 ``expires_at - now`` 计算剩余 TTL，避免长期持有 token 的调用方 误判有效期。``expires_in <= 0`` 表示已过期，调用方应触发重新获取。 @return (token, remaining_expires_in) """ cache_key = self._token_cache_key(app_id) cached = await self._cache.get(cache_key) if cached.is_some(): token, expires_at = cached.unwrap() remaining = max(int(expires_at - time.time()), 0) return token, remaining api_base_url = await self._get_channel_config("api_base_url") url = f"{api_base_url}/open-apis/auth/v3/tenant_access_token/internal" body = {"app_id": app_id, "app_secret": app_secret} resp = await self._execute_http( "POST", url, headers={}, json_body=body, ) data = self._parse_json_response(resp) token = data["tenant_access_token"] expires_in = int(data.get("expire", 0)) if expires_in <= 0: raise DependencyError( dep="feishu_api", cause=ValueError(f"invalid expire value: {expires_in}"), ) expires_at = time.time() + expires_in ttl = max(expires_in - _TOKEN_REFRESH_LEAD_TIME_SEC, 1) await self._cache.set( cache_key, (token, expires_at), ttl_seconds=ttl, ) await self._logger.debug( "Feishu tenant_access_token refreshed", app_id=app_id, expires_in=expires_in, ) return token, expires_in async def get_app_access_token( self, app_id: str, app_secret: str, ) -> str: """获取 app_access_token，缓存命中返回剩余有效期内的 token。 app_access_token 用于调用飞书 OIDC（用户令牌交换）等需要应用级 授权的端点，与 tenant_access_token（租户级）语义不同。缓存策略 对齐 ``get_tenant_access_token``：存储绝对过期时间戳，TTL 提前 ``_TOKEN_REFRESH_LEAD_TIME_SEC`` 秒刷新。 @return app_access_token 字符串。 """ cache_key = f"{_APP_TOKEN_CACHE_KEY_PREFIX}{app_id}" cached = await self._cache.get(cache_key) if cached.is_some(): token, expires_at = cached.unwrap() if expires_at > time.time(): return token api_base_url = await self._get_channel_config("api_base_url") url = f"{api_base_url}/open-apis/auth/v3/app_access_token/internal" body = {"app_id": app_id, "app_secret": app_secret} resp = await self._execute_http( "POST", url, headers={}, json_body=body, ) data = self._parse_json_response(resp) token = data["app_access_token"] expires_in = int(data.get("expire", 0)) if expires_in <= 0: raise DependencyError( dep="feishu_api", cause=ValueError(f"invalid expire value: {expires_in}"), ) expires_at = time.time() + expires_in ttl = max(expires_in - _TOKEN_REFRESH_LEAD_TIME_SEC, 1) await self._cache.set( cache_key, (token, expires_at), ttl_seconds=ttl, ) await self._logger.debug( "Feishu app_access_token refreshed", app_id=app_id, expires_in=expires_in, ) return token # ------------------------------------------------------------------ # 通用请求 # ------------------------------------------------------------------ async def request( self, method: str, path: str, account_id: str, *, json: dict | None = None, params: dict | None = None, receive_id_type: str | None = None, ) -> dict: """通用请求方法。 自动获取 tenant_access_token，注入 Authorization 头，发起 HTTP 请求并校验业务错误码。receive_id_type 非空时作为查询参数注入。 """ all_params: dict[str, Any] = dict(params) if params else {} if receive_id_type is not None: all_params["receive_id_type"] = receive_id_type return await self._request_json( method, path, account_id, json_body=json, params=all_params or None, ) # ------------------------------------------------------------------ # IM API # ------------------------------------------------------------------ async def send_message( self, account_id: str, receive_id: str, msg_type: str, content: str, receive_id_type: str = "open_id", ) -> dict: """发送消息。""" return await self.request( "POST", "/open-apis/im/v1/messages", account_id, json={ "receive_id": receive_id, "msg_type": msg_type, "content": content, }, receive_id_type=receive_id_type, ) async def update_message( self, account_id: str, message_id: str, content: str, ) -> dict: """更新消息。""" return await self.request( "PATCH", f"/open-apis/im/v1/messages/{message_id}", account_id, json={"content": content}, ) async def recall_message( self, account_id: str, message_id: str, ) -> dict: """撤回消息。""" return await self.request( "DELETE", f"/open-apis/im/v1/messages/{message_id}", account_id, ) async def get_message( self, account_id: str, message_id: str, ) -> dict: """查询消息。""" return await self.request( "GET", f"/open-apis/im/v1/messages/{message_id}", account_id, ) async def reply_message( self, account_id: str, message_id: str, msg_type: str, content: str, ) -> dict: """回复消息。""" return await self.request( "POST", f"/open-apis/im/v1/messages/{message_id}/reply", account_id, json={"msg_type": msg_type, "content": content}, ) async def batch_get_messages( self, account_id: str, message_ids: list[str], ) -> dict: """批量查询消息。""" return await self.request( "GET", "/open-apis/im/v1/messages/batch_get", account_id, params={"message_ids": ",".join(message_ids)}, ) async def update_card( self, account_id: str, message_id: str, card_content: dict, ) -> dict: """更新卡片消息。 飞书 PATCH 接口期望 ``content`` 为 JSON 字符串，对齐 ``send_message`` 的 ``msg_type=interactive`` 投递约定。 """ return await self.request( "PATCH", f"/open-apis/im/v1/messages/{message_id}", account_id, json={"content": json.dumps(card_content)}, ) async def streaming_start( self, account_id: str, receive_id: str, content: dict, receive_id_type: str = "open_id", ) -> dict: """开启流式消息。 飞书流式接口期望 ``content`` 为 JSON 字符串，对齐 ``send_message`` 与 ``update_card`` 的序列化约定。 """ return await self.request( "POST", "/open-apis/im/v1/messages/streaming", account_id, json={ "receive_id": receive_id, "content": json.dumps(content), }, receive_id_type=receive_id_type, ) async def streaming_update( self, account_id: str, message_id: str, content: dict, ) -> dict: """更新流式消息。 飞书流式接口期望 ``content`` 为 JSON 字符串，对齐 ``send_message`` 与 ``update_card`` 的序列化约定。 """ return await self.request( "PATCH", f"/open-apis/im/v1/messages/streaming/{message_id}", account_id, json={"content": json.dumps(content)}, ) async def streaming_stop( self, account_id: str, message_id: str, content: dict, ) -> dict: """结束流式消息。 飞书流式接口期望 ``content`` 为 JSON 字符串，对齐 ``send_message`` 与 ``update_card`` 的序列化约定。 """ return await self.request( "POST", f"/open-apis/im/v1/messages/streaming/{message_id}/finish", account_id, json={"content": json.dumps(content)}, ) async def add_reaction( self, account_id: str, message_id: str, emoji_type: str, ) -> dict: """添加表情回应。""" return await self.request( "POST", f"/open-apis/im/v1/messages/{message_id}/reactions", account_id, json={"reaction_type": {"emoji_type": emoji_type}}, ) async def delete_reaction( self, account_id: str, message_id: str, reaction_id: str, ) -> dict: """删除表情回应。""" return await self.request( "DELETE", f"/open-apis/im/v1/messages/{message_id}/reactions/{reaction_id}", account_id, ) async def pin_message( self, account_id: str, message_id: str, ) -> dict: """Pin 消息。""" return await self.request( "POST", "/open-apis/im/v1/pins", account_id, json={"message_id": message_id}, ) async def unpin_message( self, account_id: str, message_id: str, ) -> dict: """取消 Pin 消息。""" return await self.request( "DELETE", f"/open-apis/im/v1/pins/{message_id}", account_id, ) async def get_message_read_info( self, account_id: str, message_id: str, ) -> dict: """查询消息已读信息。 飞书返回 ``data.read_users`` 列表，含 ``user_id`` / ``read_time``。 群消息已读人数 = ``data.read_count``，目标总数 = ``data.target_count``。 """ return await self.request( "GET", f"/open-apis/im/v1/messages/{message_id}/read_info", account_id, ) async def upload_image( self, account_id: str, image_data: bytes, image_type: str = "message", ) -> dict: """上传图片（multipart/form-data）。""" return await self._request_json( "POST", "/open-apis/im/v1/images", account_id, data={"image_type": image_type}, files={"image": ("image.png", image_data)}, ) async def upload_file( self, account_id: str, file_data: bytes, file_name: str, file_type: str = "stream", ) -> dict: """上传文件（multipart/form-data）。""" return await self._request_json( "POST", "/open-apis/im/v1/files", account_id, data={"file_type": file_type, "file_name": file_name}, files={"file": (file_name, file_data)}, ) async def download_resource( self, account_id: str, message_id: str, file_key: str, file_type: str = "file", ) -> bytes: """下载资源文件，返回二进制内容。""" headers = await self._build_auth_header(account_id) api_base_url = await self._get_channel_config("api_base_url") url = f"{api_base_url}/open-apis/im/v1/messages/{message_id}/resources/{file_key}" resp = await self._execute_http( "GET", url, headers, params={"type": file_type}, ) return resp.content # ------------------------------------------------------------------ # 通讯录 API # ------------------------------------------------------------------ async def get_user( self, account_id: str, user_id: str, user_id_type: str = "open_id", ) -> dict: """查询用户信息。""" return await self.request( "GET", f"/open-apis/contact/v3/users/{user_id}", account_id, params={"user_id_type": user_id_type}, ) async def search_users( self, account_id: str, query: str, page_size: int = 50, page_token: str | None = None, ) -> dict: """搜索用户。""" params: dict[str, Any] = {"query": query, "page_size": page_size} if page_token is not None: params["page_token"] = page_token return await self.request( "GET", "/open-apis/search/v1/user", account_id, params=params, ) async def get_group_list( self, account_id: str, page_size: int = 50, page_token: str | None = None, ) -> dict: """查询群列表。""" params: dict[str, Any] = {"page_size": page_size} if page_token is not None: params["page_token"] = page_token return await self.request( "GET", "/open-apis/im/v1/chats", account_id, params=params, ) async def get_group_members( self, account_id: str, group_id: str, page_size: int = 50, page_token: str | None = None, ) -> dict: """查询群成员。""" params: dict[str, Any] = {"page_size": page_size} if page_token is not None: params["page_token"] = page_token return await self.request( "GET", f"/open-apis/im/v1/chats/{group_id}/members", account_id, params=params, ) async def get_group_detail( self, account_id: str, group_id: str, ) -> dict: """查询群详情。""" return await self.request( "GET", f"/open-apis/im/v1/chats/{group_id}", account_id, ) # ------------------------------------------------------------------ # OAuth API # ------------------------------------------------------------------ async def get_qr_login_url( self, account_id: str, redirect_uri: str, state: str, ) -> dict: """获取扫码登录 URL。""" return await self.request( "POST", "/open-apis/authen/v1/index", account_id, json={"redirect_uri": redirect_uri, "state": state}, ) async def poll_qr_login_status( self, account_id: str, login_id: str, ) -> dict: """轮询扫码登录状态。""" return await self.request( "GET", f"/open-apis/authen/v1/login_state/{login_id}", account_id, ) async def revoke_token( self, account_id: str, user_access_token: str, ) -> dict: """撤销用户 access token。 使用 user_access_token 而非 tenant_access_token 进行认证， account_id 仅用于定位渠道级 api_base_url。请求体需携带被撤销的 ``access_token``，对齐飞书 authen/v1/access_tokens/revoke 协议。 """ api_base_url = await self._get_channel_config("api_base_url") url = f"{api_base_url}/open-apis/authen/v1/access_tokens/revoke" headers = {"Authorization": f"Bearer {user_access_token}"} resp = await self._execute_http( "POST", url, headers, json_body={"access_token": user_access_token}, ) return self._parse_json_response(resp) async def exchange_oauth_code( self, app_id: str, app_secret: str, code: str, redirect_uri: str, ) -> dict: """用 OAuth 授权码交换 user_access_token。 两步流程： 1. 通过 ``get_app_access_token`` 获取 app_access_token（带缓存）。 2. 用 app_access_token 调用 OIDC token 交换端点 ``/open-apis/authen/v1/oidc/access_token``，传入 ``grant_type=authorization_code`` 与授权码。 与 ``request`` 方法不同：OIDC 端点要求 app_access_token（应用级）， 而非 tenant_access_token（租户级），因此不能复用 ``_build_auth_header``。 @return 飞书响应字典，``data`` 字段含 ``access_token`` / ``refresh_token`` / ``expires_in``。 """ app_access_token = await self.get_app_access_token(app_id, app_secret) api_base_url = await self._get_channel_config("api_base_url") url = f"{api_base_url}/open-apis/authen/v1/oidc/access_token" headers = {"Authorization": f"Bearer {app_access_token}"} resp = await self._execute_http( "POST", url, headers, json_body={ "grant_type": "authorization_code", "code": code, "redirect_uri": redirect_uri, }, ) return self._parse_json_response(resp) __all__ = ["FeishuClient"]