wpsbot 0.1.0__py3-none-any.whl

wpsbot/__init__.py

@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""WpsBot —— WPS 365 开放平台 Python SDK。
+
+提供 OAuth2 单点登录与应用机器人消息发送能力，仅依赖 requests。
+"""
+from .client import WpsBot, WpsOAuthError, normalize_user
+
+__all__ = ["WpsBot", "WpsOAuthError", "normalize_user"]
+__version__ = "0.1.0"

wpsbot/client.py

@@ -0,0 +1,471 @@
+# -*- coding: utf-8 -*-
+"""
+WpsBot —— WPS 开放平台单点登录客户端（独立可复用模块，仅依赖 requests）。
+
+特点：
+- 配置通过构造参数显式传入，不读取 .env / 环境变量
+- 完整 OAuth2 流程：授权链接 -> code 换 token -> 刷新 token
+- KSO-1 签名（HMAC-SHA256）
+- 用户信息获取（/v7/users/current 基础信息 + /v7/users/{id} 通讯录详情）
+- 自动合并两接口：头像（current）+ 部门/岗位/邮箱（detail）
+
+用法：
+    from wpsbot import WpsBot
+    bot = WpsBot(
+        client_id="你的APPID",
+        client_secret="你的APPKEY",
+        redirect_uri="http://your.domain/auth/callback",
+    )
+
+    # 1) 生成授权链接
+    auth_url = bot.build_authorize_url(state='random123')
+
+    # 2) 用回调 code 换 token
+    token = bot.exchange_code(code)
+
+    # 3) 获取当前用户完整信息（基础+详情自动合并）
+    user = bot.fetch_complete_user(token['access_token'], user_id='JV2KlR3')
+
+可配置项（均有默认值，一般只需传 client_id / client_secret / redirect_uri）：
+    scopes=['kso.user_base.read', 'kso.contact.read']  授权 scope（部门/岗位需 contact.read）
+    base_url='https://openapi.wps.cn'  开放平台地址
+    sign_enabled=True                  KSO-1 签名（KSO 接口必须签名，否则 403 invalid sign）
+    timeout=15                         请求超时（秒）
+    user_detail_enabled=True           是否自动拉取通讯录详情（部门/岗位）
+    userinfo_paths=['/v7/users/current']  用户信息接口候选路径
+"""
+import hashlib
+import hmac
+import json
+import time
+from email.utils import formatdate
+from urllib.parse import urlencode
+
+try:
+    import requests as _requests
+except ImportError:
+    raise ImportError("WpsBot 需要 requests 库: pip install requests")
+
+
+class WpsOAuthError(Exception):
+    """携带可读错误信息与原始响应。"""
+
+    def __init__(self, message, detail=None, status=None):
+        super().__init__(message)
+        self.message = message
+        self.detail = detail
+        self.status = status
+
+
+class WpsBot:
+    """
+    WPS 开放平台 OAuth2 单点登录客户端。
+
+    构造参数：
+        client_id     必填，WPS 应用 APPID
+        client_secret 必填，WPS 应用 APPKEY
+        redirect_uri  必填，授权回调地址（须与控制台配置精确一致）
+        scopes        可选，默认 ['kso.user_base.read']
+        base_url      可选，默认 'https://openapi.wps.cn'
+        sign_enabled  可选，默认 False
+        timeout       可选，默认 15
+        user_detail_enabled  可选，默认 True（自动拉取部门/岗位）
+        userinfo_paths      可选，用户信息接口候选路径
+    """
+
+    def __init__(self, client_id=None, client_secret=None, redirect_uri=None,
+                 scopes=None, base_url=None, sign_enabled=True,
+                 timeout=15, user_detail_enabled=True, userinfo_paths=None):
+        if not client_id or not client_secret or not redirect_uri:
+            raise WpsOAuthError(
+                "client_id / client_secret / redirect_uri 均必填，请通过构造参数传入")
+        self.client_id = str(client_id)
+        self.client_secret = str(client_secret)
+        self.redirect_uri = str(redirect_uri)
+        # 默认含 kso.contact.read：部门/岗位需要通讯录权限
+        self.scopes = list(scopes) if scopes else ["kso.user_base.read", "kso.contact.read"]
+        self.base_url = (base_url or "https://openapi.wps.cn").rstrip("/")
+        self.sign_enabled = bool(sign_enabled)
+        self.timeout = int(timeout)
+        self.user_detail_enabled = bool(user_detail_enabled)
+        self._userinfo_paths = list(userinfo_paths) if userinfo_paths else ["/v7/users/current"]
+
+    # ------------------------------------------------------------------ #
+    # 1. 授权链接
+    # ------------------------------------------------------------------ #
+    def build_authorize_url(self, state=""):
+        params = {
+            "client_id": self.client_id,
+            "response_type": "code",
+            "redirect_uri": self.redirect_uri,
+            "scope": ",".join(self.scopes),
+            "state": state,
+        }
+        return self.base_url + "/oauth2/auth?" + urlencode(params)
+
+    # ------------------------------------------------------------------ #
+    # 2. code 换 token / 刷新
+    # ------------------------------------------------------------------ #
+    def exchange_code(self, code):
+        return self._token_request({
+            "grant_type": "authorization_code",
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+            "code": code,
+            "redirect_uri": self.redirect_uri,
+        })
+
+    def refresh(self, refresh_token):
+        return self._token_request({
+            "grant_type": "refresh_token",
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+            "refresh_token": refresh_token,
+        })
+
+    def _token_request(self, payload):
+        url = self.base_url + "/oauth2/token"
+        try:
+            resp = _requests.post(url, data=payload,
+                                  headers={"Content-Type": "application/x-www-form-urlencoded"},
+                                  timeout=self.timeout)
+        except _requests.RequestException as exc:
+            raise WpsOAuthError("请求 token 接口失败: " + str(exc))
+
+        body = _safe_json(resp)
+        if resp.status_code != 200 or "access_token" not in body:
+            raise WpsOAuthError(
+                "换取 access_token 失败 (HTTP {0})".format(resp.status_code),
+                detail=body if body else resp.text[:2000], status=resp.status_code)
+
+        issued_at = int(time.time())
+        expires_in = int(body.get("expires_in") or 7200)
+        return {
+            "access_token": body["access_token"],
+            "token_type": body.get("token_type", "bearer"),
+            "expires_in": expires_in,
+            "expires_at": issued_at + expires_in,
+            "refresh_token": body.get("refresh_token", ""),
+            "issued_at": issued_at,
+            "raw": body,
+        }
+
+    # ------------------------------------------------------------------ #
+    # 3. KSO-1 签名
+    # ------------------------------------------------------------------ #
+    def kso1_headers(self, method, request_uri, content_type, body=b""):
+        kso_date = formatdate(timeval=None, localtime=False, usegmt=True)
+        # 严格按官方 Python 示例：请求体为空时 sha256Hex 为空字符串（不拼接）
+        sha256_hex = ""
+        if body is not None and len(body) > 0:
+            sha256_hex = hashlib.sha256(body).hexdigest()
+        data_to_sign = "KSO-1" + method.upper() + request_uri + content_type + kso_date + sha256_hex
+        signature = hmac.new(
+            self.client_secret.encode("utf-8"),
+            data_to_sign.encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+        return {
+            "X-Kso-Date": kso_date,
+            "X-Kso-Authorization": "KSO-1 " + self.client_id + ":" + signature,
+            "_data_to_sign": data_to_sign,  # 仅用于调试展示，发送前会被剔除
+        }
+
+    # ------------------------------------------------------------------ #
+    # 4. 获取用户信息
+    # ------------------------------------------------------------------ #
+    def fetch_user_info(self, access_token):
+        """按候选路径顺序尝试，返回 (normalized_user, raw_body, attempts)。
+
+        /v7/users/current 返回基础信息，含头像。
+        """
+        attempts = []
+        last_error = None
+        for path in self._userinfo_paths:
+            try:
+                status, body, debug = self._api_get(path, access_token)
+            except WpsOAuthError as exc:
+                attempts.append({"path": path, "ok": False, "error": exc.message})
+                last_error = exc
+                continue
+            code = body.get("code") if isinstance(body, dict) else None
+            data = body.get("data") if isinstance(body, dict) else None
+            record = {"path": path, "status": status, "debug": debug}
+            if status == 200 and (code in (0, None)) and data:
+                record["ok"] = True
+                attempts.append(record)
+                return normalize_user(data), body, attempts
+            record["ok"] = False
+            record["error"] = _extract_error(body, status)
+            attempts.append(record)
+            last_error = WpsOAuthError(record["error"], detail=body, status=status)
+
+        raise last_error or WpsOAuthError("获取用户信息失败：没有可用的接口路径")
+
+    def fetch_user_detail(self, access_token, user_id):
+        """用 user_id 查通讯录详情（部门、岗位、邮箱等）。需要 kso.contact.read。"""
+        path = "/v7/users/" + str(user_id)
+        try:
+            status, body, debug = self._api_get(path, access_token,
+                                                params={"with_dept": "true"})
+        except WpsOAuthError as exc:
+            return None, {"path": path, "ok": False, "error": exc.message}
+        code = body.get("code") if isinstance(body, dict) else None
+        data = body.get("data") if isinstance(body, dict) else None
+        record = {"path": path, "status": status, "debug": debug}
+        if status == 200 and (code in (0, None)) and data:
+            record["ok"] = True
+            return normalize_user(data), record
+        record["ok"] = False
+        record["error"] = _extract_error(body, status)
+        return None, record
+
+    def fetch_complete_user(self, access_token, user_id=None):
+        """获取用户完整信息：基础（头像）+ 详情（部门/岗位/邮箱）自动合并。
+
+        返回 (merged_user, debug_info)。
+        - 基础信息来自 /v7/users/current（必有头像）
+        - 详情来自 /v7/users/{id}（部门/岗位/邮箱），user_id 缺省用基础信息里的 id
+        """
+        base_user, _, attempts = self.fetch_user_info(access_token)
+        merged = dict(base_user)
+        debug = {"current": attempts, "detail": None}
+
+        uid = user_id or base_user.get("id")
+        if uid and self.user_detail_enabled:
+            detail, detail_debug = self.fetch_user_detail(access_token, uid)
+            debug["detail"] = detail_debug
+            if detail:
+                # 详情补全：不覆盖基础信息里已有的头像
+                for k, v in detail.items():
+                    if v and not merged.get(k):
+                        merged[k] = v
+        return merged, debug
+
+    def _api_get(self, path, access_token, params=None):
+        query = ("?" + urlencode(params)) if params else ""
+        request_uri = path + query
+        content_type = "application/json"
+        headers = {
+            "Authorization": "Bearer " + access_token,
+            "Content-Type": content_type,
+            "Accept": "application/json",
+        }
+        debug = {"request_uri": request_uri}
+        if self.sign_enabled:
+            sign = self.kso1_headers("GET", request_uri, content_type, b"")
+            debug["data_to_sign"] = sign.pop("_data_to_sign")
+            headers.update(sign)
+            debug["signed"] = True
+        else:
+            debug["signed"] = False
+        url = self.base_url + request_uri
+        try:
+            resp = _requests.get(url, headers=headers, timeout=self.timeout)
+        except _requests.RequestException as exc:
+            raise WpsOAuthError("请求 " + path + " 失败: " + str(exc))
+        return resp.status_code, _safe_json(resp), debug
+
+    # ------------------------------------------------------------------ #
+    # 5. 应用授权 token（发消息等应用身份接口用）
+    # ------------------------------------------------------------------ #
+    def get_app_token(self):
+        """获取应用授权 access_token（client_credentials 模式）。
+
+        用于调用应用身份接口（如发消息、通讯录管理等），与用户授权 token 不同。
+        有效期 2 小时，建议缓存复用。
+        """
+        payload = {
+            "grant_type": "client_credentials",
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+        }
+        return self._token_request(payload)
+
+    # ------------------------------------------------------------------ #
+    # 6. 发送消息（应用机器人）
+    # ------------------------------------------------------------------ #
+    def _api_post(self, path, access_token, json_body=None):
+        """POST 请求（带 KSO-1 签名 + Bearer token）"""
+        content_type = "application/json"
+        body_bytes = json.dumps(json_body, ensure_ascii=False).encode("utf-8") if json_body else b""
+        headers = {
+            "Authorization": "Bearer " + access_token,
+            "Content-Type": content_type,
+            "Accept": "application/json",
+        }
+        debug = {"request_uri": path}
+        if self.sign_enabled:
+            sign = self.kso1_headers("POST", path, content_type, body_bytes)
+            debug["data_to_sign"] = sign.pop("_data_to_sign")
+            headers.update(sign)
+            debug["signed"] = True
+        else:
+            debug["signed"] = False
+        url = self.base_url + path
+        try:
+            resp = _requests.post(url, headers=headers, data=body_bytes, timeout=self.timeout)
+        except _requests.RequestException as exc:
+            raise WpsOAuthError("请求 " + path + " 失败: " + str(exc))
+        return resp.status_code, _safe_json(resp), debug
+
+    def send_message(self, receiver_ids, content, receiver_type="user", msg_type="text",
+                     content_type="plain", app_token=None):
+        """通过应用机器人发送消息。
+
+        前提：
+        1. 开发者后台已申请权限 app:kso.chat_message.readwrite
+        2. 已设置应用可见范围（版本管理 → 可用范围），接收者必须在范围内
+        3. 应用版本已发布
+
+        Args:
+            receiver_ids: 接收者 ID（字符串或列表），用户 ID / 部门 ID / 企业 ID
+            content: 消息内容（文本字符串，或 dict 用于卡片/图片等复杂类型）
+            receiver_type: 接收者类型 "user" / "dept" / "company"
+            msg_type: 消息类型 "text" / "rich_text" / "image" / "file" / "card"
+            content_type: 文本格式 "plain" / "markdown"（仅 msg_type="text" 时有效）
+            app_token: 应用授权 token（可选，不传则自动获取）
+
+        Returns:
+            (status_code, response_body, debug_info)
+        """
+        if app_token is None:
+            app_token = self.get_app_token()["access_token"]
+
+        # 构造消息内容
+        if msg_type == "text" and isinstance(content, str):
+            msg_content = {"text": {"content": content, "type": content_type}}
+        elif isinstance(content, dict):
+            msg_content = content
+        else:
+            msg_content = {"text": {"content": str(content), "type": content_type}}
+
+        # 构造接收者
+        ids = receiver_ids if isinstance(receiver_ids, list) else [receiver_ids]
+        body = {
+            "receivers": [{
+                "type": receiver_type,
+                "receiver_ids": ids,
+            }],
+            "type": msg_type,
+            "content": msg_content,
+        }
+
+        return self._api_post("/v7/messages/batch_create", app_token, body)
+
+    def send_to_chat(self, chat_id, content, msg_type="text", content_type="plain",
+                     mentions=None, app_token=None):
+        """向群聊会话发送消息（⚠️ 机器人必须已在该群中）。
+
+        使用 /v7/messages/create 接口，receiver.type="chat"。
+        支持向指定用户(user)或会话(chat)发送即时消息。
+
+        Args:
+            chat_id: 群聊会话 ID
+            content: 消息内容（文本字符串，或 dict 用于卡片/图片等）
+            msg_type: 消息类型 text/rich_text/image/file/audio/video/card
+            content_type: 文本格式 plain/markdown（仅 msg_type="text" 时有效）
+            mentions: 被@的人员列表（可选，格式见文档）
+            app_token: 应用授权 token（可选，不传则自动获取）
+
+        Returns:
+            (status_code, response_body, debug_info)
+        """
+        if app_token is None:
+            app_token = self.get_app_token()["access_token"]
+
+        # 构造消息内容
+        if msg_type == "text" and isinstance(content, str):
+            msg_content = {"text": {"content": content, "type": content_type}}
+        elif isinstance(content, dict):
+            msg_content = content
+        else:
+            msg_content = {"text": {"content": str(content), "type": content_type}}
+
+        body = {
+            "type": msg_type,
+            "receiver": {
+                "type": "chat",
+                "receiver_id": chat_id,
+            },
+            "content": msg_content,
+        }
+        if mentions:
+            body["mentions"] = mentions
+
+        return self._api_post("/v7/messages/create", app_token, body)
+
+    def get_chat_list(self, app_token=None):
+        """获取机器人所在的会话列表（用于获取 chat_id）。
+
+        ⚠️ 机器人只能看到自己已被拉入的群聊。
+        若端点不对，可根据报错调整 path。
+        """
+        if app_token is None:
+            app_token = self.get_app_token()["access_token"]
+        return self._api_get("/v7/chats", app_token)
+
+
+# ============ 工具函数 ============ #
+def _safe_json(resp):
+    try:
+        return resp.json()
+    except (ValueError, json.JSONDecodeError):
+        return {"_raw_text": resp.text[:2000]}
+
+
+def _extract_error(body, status):
+    if isinstance(body, dict):
+        for key in ("msg", "message"):
+            if body.get(key):
+                return "HTTP " + str(status) + " | " + str(body[key])
+        if body.get("code") not in (None, 0):
+            return "HTTP " + str(status) + " | code=" + str(body["code"])
+    return "HTTP " + str(status) + " | 无有效数据"
+
+
+_NAME_KEYS = ("user_name", "name", "alias_name", "nick_name", "nickname", "real_name")
+_ID_KEYS = ("id", "user_id", "uid", "userid")
+_AVATAR_KEYS = ("avatar_url", "avatar", "avatar_big", "head_img_url", "photo")
+_EMAIL_KEYS = ("email", "mail", "business_email")
+_MOBILE_KEYS = ("mobile", "phone", "phone_number", "telephone")
+_DEPT_KEYS = ("def_dept_name", "dept_name", "department_name")
+_TITLE_KEYS = ("title", "position", "job_title", "post", "role_name")
+
+
+def _pick(d, keys):
+    if not isinstance(d, dict):
+        return ""
+    for k in keys:
+        v = d.get(k)
+        if v not in (None, "", [],):
+            return v
+    return ""
+
+
+def normalize_user(data):
+    """WPS 原始 data -> 页面友好结构。"""
+    avatar = _pick(data, _AVATAR_KEYS)
+    if isinstance(avatar, dict):
+        avatar = avatar.get("url") or avatar.get("avatar_url") or ""
+    dept_name = _pick(data, _DEPT_KEYS)
+    if not dept_name and isinstance(data.get("depts"), list) and data["depts"]:
+        first = data["depts"][0]
+        if isinstance(first, dict):
+            dept_name = first.get("dept_name") or first.get("name") or ""
+    dept_ids = data.get("dept_ids")
+    if isinstance(dept_ids, list):
+        dept_ids = ",".join(str(x) for x in dept_ids)
+    elif not dept_ids and isinstance(data.get("def_dept_id"), str):
+        dept_ids = data["def_dept_id"]
+    return {
+        "id": str(_pick(data, _ID_KEYS)),
+        "name": _pick(data, _NAME_KEYS) or "(未返回姓名)",
+        "avatar": avatar or "",
+        "email": _pick(data, _EMAIL_KEYS),
+        "mobile": _pick(data, _MOBILE_KEYS),
+        "title": _pick(data, _TITLE_KEYS),
+        "dept_name": dept_name,
+        "dept_ids": dept_ids or "",
+        "company_id": str(_pick(data, ("company_id", "corp_id", "ent_id"))),
+    }