pixelarraythirdparty 1.3.3__tar.gz → 1.3.5__tar.gz

{pixelarraythirdparty-1.3.3 → pixelarraythirdparty-1.3.5}/PKG-INFO

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

{pixelarraythirdparty-1.3.3 → pixelarraythirdparty-1.3.5}/pixelarraythirdparty/__init__.py

@@ -12,7 +12,7 @@ PixelArray 第三方微服务客户端
 - feedback: 客户反馈模块
 - project: 项目管理模块
 - support_chat: 在线客服（临时会话链接）
-- custom_events: 自定义事件（新建定义与上报）
+- custom_events: 自定义事件（新建定义、上报与报表查询）
 - project_dashboard: 项目看板（按 scope 查询 DNU/DAU/留存）
 """
 
@@ -20,7 +20,7 @@ from .support_chat.support_chat import SupportChatManagerAsync
 from .custom_events.custom_events import CustomEventsManagerAsync
 from .project_dashboard.project_dashboard import ProjectDashboardManagerAsync
 
-__version__ = "1.3.3"
+__version__ = "1.3.5"
 __author__ = "Lu qi"
 __email__ = "qi.lu@pixelarrayai.com"
 

pixelarraythirdparty-1.3.5/pixelarraythirdparty/custom_events/custom_events.py

@@ -0,0 +1,220 @@
+from pixelarraythirdparty.client import AsyncClient
+from typing import Any, Dict, List, Optional, Tuple
+
+
+class CustomEventsManagerAsync(AsyncClient):
+    """自定义事件：新建定义与上报（上报前须存在对应事件定义与字段 schema）。"""
+
+    def _dashboard_params(
+        self,
+        project_name: str,
+        *,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        top_events_limit: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        p: Dict[str, Any] = {"project_name": project_name}
+        if start_date is not None:
+            p["start_date"] = start_date
+        if end_date is not None:
+            p["end_date"] = end_date
+        if top_events_limit is not None:
+            p["top_events_limit"] = top_events_limit
+        return p
+
+    async def create_custom_event_definition(
+        self,
+        project_name: str,
+        event_key: str,
+        display_name: str,
+        *,
+        description: Optional[str] = None,
+        category: str = "custom",
+        field_schema: Optional[List[Dict[str, Any]]] = None,
+        is_active: bool = True,
+    ) -> Tuple[Dict[str, Any], bool]:
+        """
+        description:
+            新建自定义事件定义（需 API Key；与 Portal「新建定义」一致，对应 POST /api/custom-events/definitions/create）
+        parameters:
+            project_name(str): 项目名称（与 projects.name 一致）
+            event_key(str): 事件键（1~64 字符）
+            display_name(str): 展示名
+            description(str, optional): 说明
+            category(str): 分类白名单，默认 custom
+            field_schema(list, optional): 字段定义列表，每项含 name、type(string|number|boolean)、required、description
+            is_active(bool): 是否启用，默认 True
+        return:
+            data(dict): 成功时为定义记录；失败时含 message 等
+            success(bool): 是否成功
+        """
+        body: Dict[str, Any] = {
+            "project_name": project_name,
+            "event_key": event_key,
+            "display_name": display_name,
+            "category": category,
+            "field_schema": field_schema or [],
+            "is_active": is_active,
+        }
+        if description is not None:
+            body["description"] = description
+        return await self._request(
+            "POST", "/api/custom-events/definitions/create", json=body
+        )
+
+    async def get_custom_event_common_field_schema(
+        self, project_name: str
+    ) -> Tuple[Dict[str, Any], bool]:
+        """
+        description:
+            查询项目自定义事件公共维度（GET /api/custom-events/common-field-schema）
+        """
+        return await self._request(
+            "GET",
+            "/api/custom-events/common-field-schema",
+            params={"project_name": project_name},
+        )
+
+    async def update_custom_event_common_field_schema(
+        self,
+        project_name: str,
+        field_schema: List[Dict[str, Any]],
+    ) -> Tuple[Dict[str, Any], bool]:
+        """
+        description:
+            更新项目公共维度；传空列表表示恢复服务端内置默认（POST /api/custom-events/common-field-schema/update）
+        parameters:
+            field_schema: 每项含 name、type、required、可选 nullable、description
+        """
+        body: Dict[str, Any] = {
+            "project_name": project_name,
+            "field_schema": field_schema or [],
+        }
+        return await self._request(
+            "POST", "/api/custom-events/common-field-schema/update", json=body
+        )
+
+    async def report_custom_event(
+        self,
+        project_name: str,
+        event_key: str,
+        payload: Dict[str, Any],
+        client_occurred_at: Optional[str] = None,
+    ) -> Tuple[Dict[str, Any], bool]:
+        """
+        description:
+            上报单条自定义事件日志（有效载荷 = 项目公共维度 ∪ 该事件 field_schema；未传的公共键由服务端补 null）
+        parameters:
+            project_name(str): 项目名称（与 projects.name 一致）
+            event_key(str): 事件键
+            payload(dict): JSON 对象，键与类型须与定义一致
+            client_occurred_at(str, optional): 客户端事件发生时间，ISO8601 字符串
+        return:
+            data(dict): 成功时为日志记录；失败时含 message 等
+            success(bool): 是否成功
+        """
+        data: Dict[str, Any] = {
+            "project_name": project_name,
+            "event_key": event_key,
+            "payload": payload,
+        }
+        if client_occurred_at is not None:
+            data["client_occurred_at"] = client_occurred_at
+        return await self._request("POST", "/api/custom-events/report", json=data)
+
+    async def report_custom_events_batch(
+        self,
+        project_name: str,
+        items: List[Dict[str, Any]],
+    ) -> Tuple[Dict[str, Any], bool]:
+        """
+        description:
+            批量上报自定义事件（同一 project_name；任一条校验失败则整批失败）
+        parameters:
+            project_name(str): 项目名称（与 projects.name 一致）
+            items(list): 每项为 dict，须含 event_key、payload；可选 client_occurred_at（字符串）
+        return:
+            data(dict): 成功时为日志列表；失败时含 message
+            success(bool): 是否成功
+        """
+        body = {"project_name": project_name, "items": items}
+        return await self._request("POST", "/api/custom-events/report/batch", json=body)
+
+    async def get_custom_events_dashboard_summary(
+        self,
+        project_name: str,
+        *,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+    ) -> Tuple[Dict[str, Any], bool]:
+        """GET /api/custom-events/dashboard/summary：KPI 摘要（需 API Key 或 JWT）。"""
+        params = self._dashboard_params(
+            project_name, start_date=start_date, end_date=end_date
+        )
+        return await self._request(
+            "GET", "/api/custom-events/dashboard/summary", params=params
+        )
+
+    async def get_custom_events_dashboard_daily(
+        self,
+        project_name: str,
+        *,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+    ) -> Tuple[Dict[str, Any], bool]:
+        """GET /api/custom-events/dashboard/daily：按日事件量（UTC）。"""
+        params = self._dashboard_params(
+            project_name, start_date=start_date, end_date=end_date
+        )
+        return await self._request(
+            "GET", "/api/custom-events/dashboard/daily", params=params
+        )
+
+    async def get_custom_events_dashboard_top_events(
+        self,
+        project_name: str,
+        *,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        top_events_limit: Optional[int] = None,
+    ) -> Tuple[Dict[str, Any], bool]:
+        """GET /api/custom-events/dashboard/top-events：事件量 TOP N。"""
+        params = self._dashboard_params(
+            project_name,
+            start_date=start_date,
+            end_date=end_date,
+            top_events_limit=top_events_limit,
+        )
+        return await self._request(
+            "GET", "/api/custom-events/dashboard/top-events", params=params
+        )
+
+    async def get_custom_events_dashboard_by_category(
+        self,
+        project_name: str,
+        *,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+    ) -> Tuple[Dict[str, Any], bool]:
+        """GET /api/custom-events/dashboard/by-category：按分类分布。"""
+        params = self._dashboard_params(
+            project_name, start_date=start_date, end_date=end_date
+        )
+        return await self._request(
+            "GET", "/api/custom-events/dashboard/by-category", params=params
+        )
+
+    async def get_custom_events_dashboard_by_hour(
+        self,
+        project_name: str,
+        *,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+    ) -> Tuple[Dict[str, Any], bool]:
+        """GET /api/custom-events/dashboard/by-hour：按 UTC 小时分布。"""
+        params = self._dashboard_params(
+            project_name, start_date=start_date, end_date=end_date
+        )
+        return await self._request(
+            "GET", "/api/custom-events/dashboard/by-hour", params=params
+        )

{pixelarraythirdparty-1.3.3 → pixelarraythirdparty-1.3.5}/pixelarraythirdparty/project/project.py

@@ -61,6 +61,25 @@ class ProjectManagerAsync(AsyncClient):
             return data, False
         return data, True
 
+    async def rename_project(self, project_id: int, name: str):
+        """
+        description:
+            重命名项目；同步更新 external_users 中与旧项目名一致的 project_name。
+        parameters:
+            project_id(int): 项目ID
+            name(str): 新项目名称
+        return:
+            data(dict): 更新后的项目信息（含 id、name、bound_domains、created_at）
+            success(bool): 操作是否成功
+        """
+        data = {"name": name}
+        data, success = await self._request(
+            "PATCH", f"/api/projects/{project_id}/name", json=data
+        )
+        if not success:
+            return data, False
+        return data, True
+
     async def delete_project(self, project_id: int):
         """
         description:

{pixelarraythirdparty-1.3.3 → pixelarraythirdparty-1.3.5}/pixelarraythirdparty/project_dashboard/project_dashboard.py

@@ -12,6 +12,8 @@ def _resolve_dashboard_path(scope: str) -> Optional[str]:
         return "/api/project-dashboard/dashboard/dau"
     if s.upper() == "RETENTION" or s == "留存":
         return "/api/project-dashboard/dashboard/retention"
+    if s.upper() == "TOTAL_USERS" or s == "总用户":
+        return "/api/project-dashboard/dashboard/total-users"
     return None
 
 
@@ -28,13 +30,13 @@ class ProjectDashboardManagerAsync(AsyncClient):
     ) -> Tuple[Dict[str, Any], bool]:
         """
         description:
-            查询项目看板指标；scope 为 DNU、DAU、RETENTION 或中文「留存」。
+            查询项目看板指标；scope 为 DNU、DAU、RETENTION、TOTAL_USERS 或中文「留存」「总用户」。
         parameters:
             project_name(str): 项目名称（与统一登录 project_name 一致）
             scope(str): DNU | DAU | RETENTION | 留存
             start_date(str, optional): 开始日期 YYYY-MM-DD；不传则服务端默认 T-7
             end_date(str, optional): 结束日期 YYYY-MM-DD；不传则服务端默认 T-0
-            retention_days(str, optional): 仅 scope 为留存时有效；逗号分隔天数，如 2,7,14,20；不传则服务端默认
+            retention_days(str): scope 为留存时必填；逗号分隔天数，如 1,7,14,20
         return:
             data(dict): 成功时为 DauData / DnuData / RetentionData 结构（见接口文档）
             success(bool): 是否成功
@@ -42,14 +44,23 @@ class ProjectDashboardManagerAsync(AsyncClient):
         path = _resolve_dashboard_path(scope)
         if not path:
             return (
-                {"message": "scope 无效，应为 DNU、DAU、RETENTION 或 留存"},
+                {"message": "scope 无效，应为 DNU、DAU、RETENTION、TOTAL_USERS 或 留存 / 总用户"},
+                False,
+            )
+        is_retention = "/retention" in path
+        is_total_users = "/total-users" in path
+        rd = (retention_days or "").strip()
+        if is_retention and not rd:
+            return (
+                {"message": "scope 为留存时须传入 retention_days（逗号分隔正整数，如 1,7,14）"},
                 False,
             )
         params: Dict[str, Any] = {"project_name": project_name}
-        if start_date:
-            params["start_date"] = start_date
-        if end_date:
-            params["end_date"] = end_date
-        if retention_days:
-            params["retention_days"] = retention_days
+        if not is_total_users:
+            if start_date:
+                params["start_date"] = start_date
+            if end_date:
+                params["end_date"] = end_date
+        if rd:
+            params["retention_days"] = rd
         return await self._request("GET", path, params=params)

{pixelarraythirdparty-1.3.3 → pixelarraythirdparty-1.3.5}/pixelarraythirdparty.egg-info/PKG-INFO

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

{pixelarraythirdparty-1.3.3 → pixelarraythirdparty-1.3.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pixelarraythirdparty"
-version = "1.3.3"
+version = "1.3.5"
 authors = [
     {name = "Lu qi", email = "qi.lu@pixelarrayai.com"},
 ]

pixelarraythirdparty-1.3.3/pixelarraythirdparty/custom_events/custom_events.py

@@ -1,92 +0,0 @@
-from pixelarraythirdparty.client import AsyncClient
-from typing import Any, Dict, List, Optional, Tuple
-
-
-class CustomEventsManagerAsync(AsyncClient):
-    """自定义事件：新建定义与上报（上报前须存在对应事件定义与字段 schema）。"""
-
-    async def create_custom_event_definition(
-        self,
-        project_name: str,
-        event_key: str,
-        display_name: str,
-        *,
-        description: Optional[str] = None,
-        category: str = "custom",
-        field_schema: Optional[List[Dict[str, Any]]] = None,
-        is_active: bool = True,
-    ) -> Tuple[Dict[str, Any], bool]:
-        """
-        description:
-            新建自定义事件定义（需 API Key；与 Portal「新建定义」一致，对应 POST /api/custom-events/definitions/create）
-        parameters:
-            project_name(str): 项目名称（与 projects.name 一致）
-            event_key(str): 事件键（1~64 字符）
-            display_name(str): 展示名
-            description(str, optional): 说明
-            category(str): 分类白名单，默认 custom
-            field_schema(list, optional): 字段定义列表，每项含 name、type(string|number|boolean)、required、description
-            is_active(bool): 是否启用，默认 True
-        return:
-            data(dict): 成功时为定义记录；失败时含 message 等
-            success(bool): 是否成功
-        """
-        body: Dict[str, Any] = {
-            "project_name": project_name,
-            "event_key": event_key,
-            "display_name": display_name,
-            "category": category,
-            "field_schema": field_schema or [],
-            "is_active": is_active,
-        }
-        if description is not None:
-            body["description"] = description
-        return await self._request(
-            "POST", "/api/custom-events/definitions/create", json=body
-        )
-
-    async def report_custom_event(
-        self,
-        project_name: str,
-        event_key: str,
-        payload: Dict[str, Any],
-        client_occurred_at: Optional[str] = None,
-    ) -> Tuple[Dict[str, Any], bool]:
-        """
-        description:
-            上报单条自定义事件日志（JSON 载荷须符合 Portal 中配置的 field_schema）
-        parameters:
-            project_name(str): 项目名称（与 projects.name 一致）
-            event_key(str): 事件键
-            payload(dict): JSON 对象，键与类型须与定义一致
-            client_occurred_at(str, optional): 客户端事件发生时间，ISO8601 字符串
-        return:
-            data(dict): 成功时为日志记录；失败时含 message 等
-            success(bool): 是否成功
-        """
-        data: Dict[str, Any] = {
-            "project_name": project_name,
-            "event_key": event_key,
-            "payload": payload,
-        }
-        if client_occurred_at is not None:
-            data["client_occurred_at"] = client_occurred_at
-        return await self._request("POST", "/api/custom-events/report", json=data)
-
-    async def report_custom_events_batch(
-        self,
-        project_name: str,
-        items: List[Dict[str, Any]],
-    ) -> Tuple[Dict[str, Any], bool]:
-        """
-        description:
-            批量上报自定义事件（同一 project_name；任一条校验失败则整批失败）
-        parameters:
-            project_name(str): 项目名称（与 projects.name 一致）
-            items(list): 每项为 dict，须含 event_key、payload；可选 client_occurred_at（字符串）
-        return:
-            data(dict): 成功时为日志列表；失败时含 message
-            success(bool): 是否成功
-        """
-        body = {"project_name": project_name, "items": items}
-        return await self._request("POST", "/api/custom-events/report/batch", json=body)