pixelarraythirdparty 1.2.2__py3-none-any.whl → 1.2.4__py3-none-any.whl

pixelarraythirdparty/__init__.py

@@ -13,7 +13,7 @@ PixelArray 第三方微服务客户端
 - project: 项目管理模块
 """
 
-__version__ = "1.2.2"
+__version__ = "1.2.4"
 __author__ = "Lu qi"
 __email__ = "qi.lu@pixelarrayai.com"
 

pixelarraythirdparty/unified_login/unified_login.py

@@ -9,43 +9,29 @@ from pixelarraythirdparty.client import AsyncClient
 class OAuth2Login(AsyncClient):
     """
     统一的 OAuth2 登录客户端基类
-    
+
     支持所有基于 OAuth2 的第三方登录（Google、微信、GitHub、GitLab、抖音等）
     通过配置不同的端点来支持不同的提供商
-    
+
     使用示例:
     ```
-    # Google登录
-    google = OAuth2Login(
-        api_key="your_api_key",
-        provider="google"
-    )
-    user_info, success = await google.login()
-    
-    # 微信PC端扫码登录
-    wechat = OAuth2Login(
-        api_key="your_api_key",
-        provider="wechat",
-        login_type="desktop"
-    )
-    user_info, success = await wechat.login()
-    
-    # 微信手机端登录
-    wechat_mobile = OAuth2Login(
+    # 服务端使用场景（推荐）
+    oauth2_login = OAuth2Login(
         api_key="your_api_key",
-        provider="wechat",
-        login_type="mobile"
+        provider="google" # 支持的提供商：google, wechat, github, gitlab, douyin
     )
-    user_info, success = await wechat_mobile.login()
-    
-    # 支持refresh_token的提供商（如Google、GitLab）
-    if user_info.get("refresh_token"):
-        token_data, success = await google.refresh_access_token(
-            user_info.get("refresh_token")
-        )
+    # 1. 获取授权URL
+    auth_data, success = await oauth2_login.get_auth_url()
+    if success:
+        auth_url = auth_data.get("auth_url")
+        state = auth_data.get("state")
+        # 将auth_url返回给前端，让用户点击授权
+        # 2. 等待登录结果（在服务端轮询）
+        user_info, success = await oauth2_login.wait_for_login(state, timeout=180)
+        print(user_info, success)
     ```
     """
-    
+
     # 提供商端点映射
     PROVIDER_ENDPOINTS = {
         "google": {
@@ -75,13 +61,8 @@ class OAuth2Login(AsyncClient):
             "wait_login": "/api/unified-login/douyin/wait-login",
         },
     }
-    
-    def __init__(
-        self,
-        api_key: str,
-        provider: str,
-        login_type: Optional[str] = None
-    ):
+
+    def __init__(self, api_key: str, provider: str, login_type: Optional[str] = None):
         """
         description:
             初始化OAuth2登录客户端
@@ -93,19 +74,19 @@ class OAuth2Login(AsyncClient):
         super().__init__(api_key)
         self.provider = provider.lower()
         self.login_type = login_type
-        
+
         # 验证提供商是否支持
         if self.provider not in self.PROVIDER_ENDPOINTS:
             raise ValueError(
                 f"不支持的提供商: {provider}。"
                 f"支持的提供商: {', '.join(self.PROVIDER_ENDPOINTS.keys())}"
             )
-        
+
         # 微信特殊处理：根据login_type选择不同的端点
         if self.provider == "wechat":
             if login_type == "mobile":
                 self.provider = "wechat-official"
-    
+
     def _get_endpoint(self, endpoint_type: str) -> str:
         """
         description:
@@ -118,15 +99,16 @@ class OAuth2Login(AsyncClient):
         endpoints = self.PROVIDER_ENDPOINTS.get(self.provider, {})
         endpoint = endpoints.get(endpoint_type)
         if not endpoint:
-            raise ValueError(
-                f"提供商 {self.provider} 不支持 {endpoint_type} 端点"
-            )
+            raise ValueError(f"提供商 {self.provider} 不支持 {endpoint_type} 端点")
         return endpoint
-    
-    async def _get_auth_url(self) -> Tuple[Optional[Dict[str, str]], bool]:
+
+    async def get_auth_url(self) -> Tuple[Optional[Dict[str, str]], bool]:
         """
         description:
-            获取OAuth授权URL
+            获取OAuth授权URL（公共方法，供服务端调用）
+
+            服务端应该调用此方法获取授权URL，然后将URL返回给前端让用户点击授权。
+            获取到state后，使用wait_for_login方法等待登录结果。
         return:
             auth_data(dict, optional): 授权数据字典，包含auth_url和state
             success(bool): 是否成功
@@ -139,37 +121,17 @@ class OAuth2Login(AsyncClient):
         if not auth_url:
             return None, False
         return data, True
-    
-    def _extract_state(self, auth_url: Optional[str]) -> Optional[str]:
-        """
-        description:
-            从授权URL中提取state参数
-        parameters:
-            auth_url(str, optional): 授权URL
-        return:
-            state(str, optional): state参数值，如果提取失败则返回None
-        """
-        if not auth_url:
-            return None
-        try:
-            parsed = urllib.parse.urlparse(auth_url)
-            query = urllib.parse.parse_qs(parsed.query)
-            values = query.get("state")
-            if values:
-                return values[0]
-        except Exception:
-            return None
-        return None
-    
-    async def _wait_for_login(
-        self, state: str, timeout: int
-    ) -> Tuple[Dict, bool]:
+
+    async def wait_for_login(self, state: str, timeout: int = 180) -> Tuple[Dict, bool]:
         """
         description:
-            等待登录结果，轮询检查登录状态
+            等待登录结果，轮询检查登录状态（公共方法，供服务端调用）
+
+            服务端在用户点击授权后，调用此方法轮询等待登录结果。
+            此方法会持续轮询直到登录成功或超时。
         parameters:
-            state(str): 登录状态标识
-            timeout(int): 超时时间（秒）
+            state(str): 登录状态标识，从get_auth_url返回的auth_data中获取
+            timeout(int, optional): 超时时间（秒），默认为180
         return:
             user_info(dict): 用户信息字典
             success(bool): 是否成功
@@ -177,53 +139,29 @@ class OAuth2Login(AsyncClient):
         interval = 2
         total_checks = max(1, timeout // interval) if timeout > 0 else 1
         endpoint = self._get_endpoint("wait_login")
-        
+
         for _ in range(total_checks):
             status, response = await self._request_raw(
                 "POST",
                 endpoint,
                 json={"state": state},
             )
-            
+
             if status == 200 and response.get("success") is True:
                 return response.get("data", {}), True
-            
+
             if status in (400, 408):
                 break
-            
+
             await asyncio.sleep(interval)
-        
+
         return {}, False
-    
-    async def login(self, timeout: int = 180) -> Tuple[Dict, bool]:
-        """
-        description:
-            仿 Supabase CLI 的一键登录流程：打开浏览器完成授权，终端端轮询等待登录结果
-        parameters:
-            timeout(int, optional): 等待用户完成授权的超时时间（秒），默认为180
-        return:
-            user_info(dict): 用户信息字典
-            success(bool): 是否成功
-        """
-        auth_data, success = await self._get_auth_url()
-        if not success or not auth_data:
-            return {}, False
-        
-        auth_url = auth_data.get("auth_url")
-        state = auth_data.get("state") or self._extract_state(auth_url)
-        
-        if not auth_url or not state:
-            return {}, False
-        
-        webbrowser.open(auth_url, new=2)
-        
-        return await self._wait_for_login(state, timeout)
-    
+
     async def refresh_access_token(self, refresh_token: str) -> Tuple[Dict, bool]:
         """
         description:
             使用refresh_token刷新access_token（仅支持Google和GitLab）
-            
+
             注意：GitLab 采用 token rotation（令牌轮换）机制，每次刷新时会返回新的 refresh_token，
             旧的 refresh_token 会立即失效。必须保存新的 refresh_token 并替换旧的。
             Google 也可能在某些情况下返回新的 refresh_token。
@@ -237,7 +175,7 @@ class OAuth2Login(AsyncClient):
             endpoint = self._get_endpoint("refresh_token")
         except ValueError:
             return {}, False
-        
+
         data, success = await self._request(
             "POST",
             endpoint,
@@ -254,27 +192,32 @@ class GoogleLogin(AsyncClient):
 
     使用示例:
     ```
+    # 服务端使用场景（推荐）
     google = GoogleLogin(api_key="your_api_key")
-    user_info, success = await google.login()
+    # 1. 获取授权URL
+    auth_data, success = await google.get_auth_url()
     if success:
-        access_token = user_info.get("access_token")
-        refresh_token = user_info.get("refresh_token")
-        
-        # 使用refresh_token刷新access_token
-        if refresh_token:
-            token_data, success = await google.refresh_access_token(refresh_token)
-            if success:
-                new_access_token = token_data.get("access_token")
+        auth_url = auth_data.get("auth_url")
+        state = auth_data.get("state")
+        # 将auth_url返回给前端，让用户点击授权
+        # 2. 等待登录结果（在服务端轮询）
+        user_info, success = await google.wait_for_login(state, timeout=180)
+        if success:
+            access_token = user_info.get("access_token")
+            refresh_token = user_info.get("refresh_token")
     ```
     """
 
     def __init__(self, api_key: str):
         super().__init__(api_key)
 
-    async def _get_auth_url(self) -> Tuple[Optional[Dict[str, str]], bool]:
+    async def get_auth_url(self) -> Tuple[Optional[Dict[str, str]], bool]:
         """
         description:
-            获取Google OAuth授权URL
+            获取Google OAuth授权URL（公共方法，供服务端调用）
+
+            服务端应该调用此方法获取授权URL，然后将URL返回给前端让用户点击授权。
+            获取到state后，使用wait_for_login方法等待登录结果。
         return:
             auth_data(dict, optional): 授权数据字典，包含auth_url和state
             success(bool): 是否成功
@@ -289,52 +232,16 @@ class GoogleLogin(AsyncClient):
             return None, False
         return data, True
 
-    async def login(self, timeout: int = 180) -> Tuple[Dict, bool]:
+    async def wait_for_login(self, state: str, timeout: int = 180) -> Tuple[Dict, bool]:
         """
         description:
-            仿 Supabase CLI 的一键登录流程：打开浏览器完成授权，终端端轮询等待登录结果
-        parameters:
-            timeout(int, optional): 等待用户完成授权的超时时间（秒），默认为180
-        return:
-            user_info(dict): 用户信息字典
-            success(bool): 是否成功
-        """
-        auth_data, success = await self._get_auth_url()
-        if not success or not auth_data:
-            return {}, False
-
-        auth_url = auth_data.get("auth_url")
-        state = auth_data.get("state") or self._extract_state(auth_url)
-
-        if not auth_url or not state:
-            return {}, False
+            等待Google登录结果，轮询检查登录状态（公共方法，供服务端调用）
 
-        webbrowser.open(auth_url, new=2)
-
-        return await self._wait_for_google_login(state, timeout)
-
-    def _extract_state(self, auth_url: Optional[str]) -> Optional[str]:
-        if not auth_url:
-            return None
-        try:
-            parsed = urllib.parse.urlparse(auth_url)
-            query = urllib.parse.parse_qs(parsed.query)
-            values = query.get("state")
-            if values:
-                return values[0]
-        except Exception:
-            return None
-        return None
-
-    async def _wait_for_google_login(
-        self, state: str, timeout: int
-    ) -> Tuple[Dict, bool]:
-        """
-        description:
-            等待Google登录结果，轮询检查登录状态
+            服务端在用户点击授权后，调用此方法轮询等待登录结果。
+            此方法会持续轮询直到登录成功或超时。
         parameters:
-            state(str): 登录状态标识
-            timeout(int): 超时时间（秒）
+            state(str): 登录状态标识，从get_auth_url返回的auth_data中获取
+            timeout(int, optional): 超时时间（秒），默认为180
         return:
             user_info(dict): 用户信息字典
             success(bool): 是否成功
@@ -382,28 +289,49 @@ class GoogleLogin(AsyncClient):
 class WechatLogin(AsyncClient):
     """
     微信 OAuth2 登录客户端
-    
+
     支持两种登录方式：
     - desktop: PC端扫码登录（使用微信开放平台）
     - mobile: 微信公众号OAuth登录（手机端微信内打开）
 
     使用示例:
     ```
+    # 服务端使用场景（推荐）
     wechat = WechatLogin(api_key="your_api_key")
     # PC端扫码登录
-    user_info, success = await wechat.login(login_type="desktop")
+    auth_data, success = await wechat.get_auth_url(login_type="desktop")
+    if success:
+        auth_url = auth_data.get("auth_url")
+        state = auth_data.get("state")
+        # 将auth_url返回给前端，让用户扫码授权
+        # 等待登录结果
+        user_info, success = await wechat.wait_for_login(state, timeout=180, login_type="desktop")
+        print(user_info, success)
+
     # 微信公众号登录（手机端）
-    user_info, success = await wechat.login(login_type="mobile")
+    auth_data, success = await wechat.get_auth_url(login_type="mobile")
+    if success:
+        auth_url = auth_data.get("auth_url")
+        state = auth_data.get("state")
+        # 将auth_url返回给前端，让用户在微信内打开授权
+        # 等待登录结果
+        user_info, success = await wechat.wait_for_login(state, timeout=180, login_type="mobile")
+        print(user_info, success)
     ```
     """
 
     def __init__(self, api_key: str):
         super().__init__(api_key)
 
-    async def _get_auth_url(self, login_type: str = "desktop") -> Tuple[Optional[Dict[str, str]], bool]:
+    async def get_auth_url(
+        self, login_type: str = "desktop"
+    ) -> Tuple[Optional[Dict[str, str]], bool]:
         """
         description:
-            获取微信授权URL
+            获取微信授权URL（公共方法，供服务端调用）
+
+            服务端应该调用此方法获取授权URL，然后将URL返回给前端让用户点击授权。
+            获取到state后，使用wait_for_login方法等待登录结果。
         parameters:
             login_type(str, optional): 登录类型，desktop表示PC端扫码登录，mobile表示微信公众号登录，默认为desktop
         return:
@@ -416,7 +344,7 @@ class WechatLogin(AsyncClient):
         else:
             # PC端扫码登录
             endpoint = "/api/unified-login/wechat/auth-url"
-        
+
         data, success = await self._request("POST", endpoint)
         if not success:
             return None, False
@@ -425,61 +353,18 @@ class WechatLogin(AsyncClient):
             return None, False
         return data, True
 
-    async def login(self, login_type: str = "desktop", timeout: int = 180) -> Tuple[Dict, bool]:
-        """
-        description:
-            仿 Supabase CLI 的一键登录流程：打开浏览器完成授权，终端端轮询等待登录结果
-        parameters:
-            login_type(str, optional): 登录类型，desktop表示PC端扫码登录，mobile表示微信公众号登录，默认为desktop
-            timeout(int, optional): 等待用户完成授权的超时时间（秒），默认为180
-        return:
-            user_info(dict): 用户信息字典
-            success(bool): 是否成功
-        """
-        auth_data, success = await self._get_auth_url(login_type)
-        if not success or not auth_data:
-            return {}, False
-
-        auth_url = auth_data.get("auth_url")
-        state = auth_data.get("state") or self._extract_state(auth_url)
-
-        if not auth_url or not state:
-            return {}, False
-
-        webbrowser.open(auth_url, new=2)
-
-        return await self._wait_for_wechat_login(state, timeout, login_type)
-
-    def _extract_state(self, auth_url: Optional[str]) -> Optional[str]:
-        """
-        description:
-            从授权URL中提取state参数
-        parameters:
-            auth_url(str, optional): 授权URL
-        return:
-            state(str, optional): state参数值，如果提取失败则返回None
-        """
-        if not auth_url:
-            return None
-        try:
-            parsed = urllib.parse.urlparse(auth_url)
-            query = urllib.parse.parse_qs(parsed.query)
-            values = query.get("state")
-            if values:
-                return values[0]
-        except Exception:
-            return None
-        return None
-
-    async def _wait_for_wechat_login(
-        self, state: str, timeout: int, login_type: str = "desktop"
+    async def wait_for_login(
+        self, state: str, timeout: int = 180, login_type: str = "desktop"
     ) -> Tuple[Dict, bool]:
         """
         description:
-            等待微信登录结果，轮询检查登录状态
+            等待微信登录结果，轮询检查登录状态（公共方法，供服务端调用）
+
+            服务端在用户点击授权后，调用此方法轮询等待登录结果。
+            此方法会持续轮询直到登录成功或超时。
         parameters:
-            state(str): 登录状态标识
-            timeout(int): 超时时间（秒）
+            state(str): 登录状态标识，从get_auth_url返回的auth_data中获取
+            timeout(int, optional): 超时时间（秒），默认为180
             login_type(str, optional): 登录类型，desktop表示PC端扫码登录，mobile表示微信公众号登录，默认为desktop
         return:
             user_info(dict): 用户信息字典
@@ -518,18 +403,30 @@ class GitHubLogin(AsyncClient):
 
     使用示例:
     ```
+    # 服务端使用场景（推荐）
     github = GitHubLogin(api_key="your_api_key")
-    user_info, success = await github.login()
+    # 1. 获取授权URL
+    auth_data, success = await github.get_auth_url()
+    if success:
+        auth_url = auth_data.get("auth_url")
+        state = auth_data.get("state")
+        # 将auth_url返回给前端，让用户点击授权
+        # 2. 等待登录结果（在服务端轮询）
+        user_info, success = await github.wait_for_login(state, timeout=180)
+        print(user_info, success)
     ```
     """
 
     def __init__(self, api_key: str):
         super().__init__(api_key)
 
-    async def _get_auth_url(self) -> Tuple[Optional[Dict[str, str]], bool]:
+    async def get_auth_url(self) -> Tuple[Optional[Dict[str, str]], bool]:
         """
         description:
-            获取GitHub OAuth授权URL
+            获取GitHub OAuth授权URL（公共方法，供服务端调用）
+
+            服务端应该调用此方法获取授权URL，然后将URL返回给前端让用户点击授权。
+            获取到state后，使用wait_for_login方法等待登录结果。
         return:
             auth_data(dict, optional): 授权数据字典，包含auth_url和state
             success(bool): 是否成功
@@ -544,60 +441,16 @@ class GitHubLogin(AsyncClient):
             return None, False
         return data, True
 
-    async def login(self, timeout: int = 180) -> Tuple[Dict, bool]:
+    async def wait_for_login(self, state: str, timeout: int = 180) -> Tuple[Dict, bool]:
         """
         description:
-            仿 Supabase CLI 的一键登录流程：打开浏览器完成授权，终端端轮询等待登录结果
-        parameters:
-            timeout(int, optional): 等待用户完成授权的超时时间（秒），默认为180
-        return:
-            user_info(dict): 用户信息字典
-            success(bool): 是否成功
-        """
-        auth_data, success = await self._get_auth_url()
-        if not success or not auth_data:
-            return {}, False
-
-        auth_url = auth_data.get("auth_url")
-        state = auth_data.get("state") or self._extract_state(auth_url)
-
-        if not auth_url or not state:
-            return {}, False
+            等待GitHub登录结果，轮询检查登录状态（公共方法，供服务端调用）
 
-        webbrowser.open(auth_url, new=2)
-
-        return await self._wait_for_github_login(state, timeout)
-
-    def _extract_state(self, auth_url: Optional[str]) -> Optional[str]:
-        """
-        description:
-            从授权URL中提取state参数
-        parameters:
-            auth_url(str, optional): 授权URL
-        return:
-            state(str, optional): state参数值，如果提取失败则返回None
-        """
-        if not auth_url:
-            return None
-        try:
-            parsed = urllib.parse.urlparse(auth_url)
-            query = urllib.parse.parse_qs(parsed.query)
-            values = query.get("state")
-            if values:
-                return values[0]
-        except Exception:
-            return None
-        return None
-
-    async def _wait_for_github_login(
-        self, state: str, timeout: int
-    ) -> Tuple[Dict, bool]:
-        """
-        description:
-            等待GitHub登录结果，轮询检查登录状态
+            服务端在用户点击授权后，调用此方法轮询等待登录结果。
+            此方法会持续轮询直到登录成功或超时。
         parameters:
-            state(str): 登录状态标识
-            timeout(int): 超时时间（秒）
+            state(str): 登录状态标识，从get_auth_url返回的auth_data中获取
+            timeout(int, optional): 超时时间（秒），默认为180
         return:
             user_info(dict): 用户信息字典
             success(bool): 是否成功
@@ -629,18 +482,30 @@ class DouyinLogin(AsyncClient):
 
     使用示例:
     ```
+    # 服务端使用场景（推荐）
     douyin = DouyinLogin(api_key="your_api_key")
-    user_info, success = await douyin.login()
+    # 1. 获取授权URL
+    auth_data, success = await douyin.get_auth_url()
+    if success:
+        auth_url = auth_data.get("auth_url")
+        state = auth_data.get("state")
+        # 将auth_url返回给前端，让用户点击授权
+        # 2. 等待登录结果（在服务端轮询）
+        user_info, success = await douyin.wait_for_login(state, timeout=180)
+        print(user_info, success)
     ```
     """
 
     def __init__(self, api_key: str):
         super().__init__(api_key)
 
-    async def _get_auth_url(self) -> Tuple[Optional[Dict[str, str]], bool]:
+    async def get_auth_url(self) -> Tuple[Optional[Dict[str, str]], bool]:
         """
         description:
-            获取抖音OAuth授权URL
+            获取抖音OAuth授权URL（公共方法，供服务端调用）
+
+            服务端应该调用此方法获取授权URL，然后将URL返回给前端让用户点击授权。
+            获取到state后，使用wait_for_login方法等待登录结果。
         return:
             auth_data(dict, optional): 授权数据字典，包含auth_url和state
             success(bool): 是否成功
@@ -655,60 +520,16 @@ class DouyinLogin(AsyncClient):
             return None, False
         return data, True
 
-    async def login(self, timeout: int = 180) -> Tuple[Dict, bool]:
+    async def wait_for_login(self, state: str, timeout: int = 180) -> Tuple[Dict, bool]:
         """
         description:
-            仿 Supabase CLI 的一键登录流程：打开浏览器完成授权，终端端轮询等待登录结果
-        parameters:
-            timeout(int, optional): 等待用户完成授权的超时时间（秒），默认为180
-        return:
-            user_info(dict): 用户信息字典
-            success(bool): 是否成功
-        """
-        auth_data, success = await self._get_auth_url()
-        if not success or not auth_data:
-            return {}, False
+            等待抖音登录结果，轮询检查登录状态（公共方法，供服务端调用）
 
-        auth_url = auth_data.get("auth_url")
-        state = auth_data.get("state") or self._extract_state(auth_url)
-
-        if not auth_url or not state:
-            return {}, False
-
-        webbrowser.open(auth_url, new=2)
-
-        return await self._wait_for_douyin_login(state, timeout)
-
-    def _extract_state(self, auth_url: Optional[str]) -> Optional[str]:
-        """
-        description:
-            从授权URL中提取state参数
-        parameters:
-            auth_url(str, optional): 授权URL
-        return:
-            state(str, optional): state参数值，如果提取失败则返回None
-        """
-        if not auth_url:
-            return None
-        try:
-            parsed = urllib.parse.urlparse(auth_url)
-            query = urllib.parse.parse_qs(parsed.query)
-            values = query.get("state")
-            if values:
-                return values[0]
-        except Exception:
-            return None
-        return None
-
-    async def _wait_for_douyin_login(
-        self, state: str, timeout: int
-    ) -> Tuple[Dict, bool]:
-        """
-        description:
-            等待抖音登录结果，轮询检查登录状态
+            服务端在用户点击授权后，调用此方法轮询等待登录结果。
+            此方法会持续轮询直到登录成功或超时。
         parameters:
-            state(str): 登录状态标识
-            timeout(int): 超时时间（秒）
+            state(str): 登录状态标识，从get_auth_url返回的auth_data中获取
+            timeout(int, optional): 超时时间（秒），默认为180
         return:
             user_info(dict): 用户信息字典
             success(bool): 是否成功
@@ -740,15 +561,34 @@ class GitLabLogin(AsyncClient):
 
     使用示例:
     ```
+    # 服务端使用场景（推荐）
     gitlab = GitLabLogin(api_key="your_api_key")
-    user_info, success = await gitlab.login()
+    # 1. 获取授权URL
+    auth_data, success = await gitlab.get_auth_url()
+    if success:
+        auth_url = auth_data.get("auth_url")
+        state = auth_data.get("state")
+        # 将auth_url返回给前端，让用户点击授权
+        # 2. 等待登录结果（在服务端轮询）
+        user_info, success = await gitlab.wait_for_login(state, timeout=180)
+        print(user_info, success)
     ```
     """
 
     def __init__(self, api_key: str):
         super().__init__(api_key)
 
-    async def _get_auth_url(self) -> Tuple[Optional[Dict[str, str]], bool]:
+    async def get_auth_url(self) -> Tuple[Optional[Dict[str, str]], bool]:
+        """
+        description:
+            获取GitLab OAuth授权URL（公共方法，供服务端调用）
+
+            服务端应该调用此方法获取授权URL，然后将URL返回给前端让用户点击授权。
+            获取到state后，使用wait_for_login方法等待登录结果。
+        return:
+            auth_data(dict, optional): 授权数据字典，包含auth_url和state
+            success(bool): 是否成功
+        """
         data, success = await self._request(
             "POST", "/api/unified-login/gitlab/auth-url"
         )
@@ -759,43 +599,20 @@ class GitLabLogin(AsyncClient):
             return None, False
         return data, True
 
-    async def login(self, timeout: int = 180) -> Tuple[Dict, bool]:
+    async def wait_for_login(self, state: str, timeout: int = 180) -> Tuple[Dict, bool]:
         """
-        仿 Supabase CLI 的一键登录流程：打开浏览器完成授权，
-        终端端轮询等待登录结果
+        description:
+            等待GitLab登录结果，轮询检查登录状态（公共方法，供服务端调用）
 
-        :param timeout: 等待用户完成授权的超时时间（秒）
+            服务端在用户点击授权后，调用此方法轮询等待登录结果。
+            此方法会持续轮询直到登录成功或超时。
+        parameters:
+            state(str): 登录状态标识，从get_auth_url返回的auth_data中获取
+            timeout(int, optional): 超时时间（秒），默认为180
+        return:
+            user_info(dict): 用户信息字典
+            success(bool): 是否成功
         """
-        auth_data, success = await self._get_auth_url()
-        if not success or not auth_data:
-            return {}, False
-
-        auth_url = auth_data.get("auth_url")
-        state = auth_data.get("state") or self._extract_state(auth_url)
-
-        if not auth_url or not state:
-            return {}, False
-
-        webbrowser.open(auth_url, new=2)
-
-        return await self._wait_for_gitlab_login(state, timeout)
-
-    def _extract_state(self, auth_url: Optional[str]) -> Optional[str]:
-        if not auth_url:
-            return None
-        try:
-            parsed = urllib.parse.urlparse(auth_url)
-            query = urllib.parse.parse_qs(parsed.query)
-            values = query.get("state")
-            if values:
-                return values[0]
-        except Exception:
-            return None
-        return None
-
-    async def _wait_for_gitlab_login(
-        self, state: str, timeout: int
-    ) -> Tuple[Dict, bool]:
         interval = 2
         total_checks = max(1, timeout // interval) if timeout > 0 else 1
 
@@ -820,7 +637,7 @@ class GitLabLogin(AsyncClient):
         """
         description:
             使用refresh_token刷新access_token
-            
+
             注意：GitLab 采用 token rotation（令牌轮换）机制，每次刷新时会返回新的 refresh_token，
             旧的 refresh_token 会立即失效。必须保存新的 refresh_token 并替换旧的。
         parameters:
@@ -884,9 +701,7 @@ class SMSLogin(AsyncClient):
         )
         return bool(success)
 
-    async def _wait_for_login(
-        self, phone: str, timeout: int
-    ) -> Tuple[Dict, bool]:
+    async def _wait_for_login(self, phone: str, timeout: int) -> Tuple[Dict, bool]:
         """
         等待短信登录结果
 
@@ -976,9 +791,7 @@ class EmailLogin(AsyncClient):
         )
         return bool(success)
 
-    async def _wait_for_login(
-        self, email: str, timeout: int
-    ) -> Tuple[Dict, bool]:
+    async def _wait_for_login(self, email: str, timeout: int) -> Tuple[Dict, bool]:
         """
         等待邮箱登录结果
 

{pixelarraythirdparty-1.2.2.dist-info → pixelarraythirdparty-1.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pixelarraythirdparty
-Version: 1.2.2
+Version: 1.2.4
 Summary: PixelArray 第三方微服务客户端
 Author-email: Lu qi <qi.lu@pixelarrayai.com>
 License-Expression: MIT

{pixelarraythirdparty-1.2.2.dist-info → pixelarraythirdparty-1.2.4.dist-info}/RECORD

@@ -1,4 +1,4 @@
-pixelarraythirdparty/__init__.py,sha256=nJENJpeEcGI9wm3q8bM__BslEPtmFVRN3-ZqeV_0Bd4,582
+pixelarraythirdparty/__init__.py,sha256=ZPQ3uKaT_Scaf4p_JVcXXb90OdZ01QLEkXh57BGGnuY,582
 pixelarraythirdparty/client.py,sha256=Ym_IZ6cdoZJoMKW61ZRTfQ81-Hay5dpLTgExoANZwI4,3171
 pixelarraythirdparty/cron/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pixelarraythirdparty/cron/cron.py,sha256=nv4e2hX_UkEJ-kbEARbInU2J6aREyYZ61dZ-4b9UWJI,3146
@@ -11,11 +11,11 @@ pixelarraythirdparty/product/product.py,sha256=5fgv2Ck860epYXxipY83vePziubCIlocF
 pixelarraythirdparty/project/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pixelarraythirdparty/project/project.py,sha256=a8swjckyn4y3NlIx0-tMbcRwDY9woOijGi7lb1wN7Ok,2455
 pixelarraythirdparty/unified_login/__init__.py,sha256=tzy3nmRv-qZID-6kYRFarqQVrmkUsEI7D6de_PFu7Tg,327
-pixelarraythirdparty/unified_login/unified_login.py,sha256=Klz8Jb-8qIy6Sc1okQS7SQe_ByS0CpO_AvbDnLJnUwM,32700
+pixelarraythirdparty/unified_login/unified_login.py,sha256=chpB8Yj6yoPrh821LRe4BbDlLkK4Kn9n5X6FBiINUp0,29007
 pixelarraythirdparty/user/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pixelarraythirdparty/user/user.py,sha256=SqufSAVMxQElz-NqtlOZs_dG7UtbuE-ygLAyml9oKpY,5761
-pixelarraythirdparty-1.2.2.dist-info/licenses/LICENSE,sha256=O-g1dUr0U50rSIvmWE9toiVkSgFpVt72_MHITbWvAqA,1067
-pixelarraythirdparty-1.2.2.dist-info/METADATA,sha256=TC042i-Yca5TeDXqu5xereatr-bwINhP_9xLoTpi6qE,993
-pixelarraythirdparty-1.2.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pixelarraythirdparty-1.2.2.dist-info/top_level.txt,sha256=dzG2Ut8j7noUqj_0ZQjcIDAeHYCh_9WtlxjAxtoyufo,21
-pixelarraythirdparty-1.2.2.dist-info/RECORD,,
+pixelarraythirdparty-1.2.4.dist-info/licenses/LICENSE,sha256=O-g1dUr0U50rSIvmWE9toiVkSgFpVt72_MHITbWvAqA,1067
+pixelarraythirdparty-1.2.4.dist-info/METADATA,sha256=2m92kvoPsCInrZsLpS094MxadQzGipcKcYtlEqa6GHY,993
+pixelarraythirdparty-1.2.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pixelarraythirdparty-1.2.4.dist-info/top_level.txt,sha256=dzG2Ut8j7noUqj_0ZQjcIDAeHYCh_9WtlxjAxtoyufo,21
+pixelarraythirdparty-1.2.4.dist-info/RECORD,,