ecapi-sdk 0.1.0__tar.gz

ecapi_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: ecapi-sdk
+Version: 0.1.0
+Summary: ECAPI SDK for Python
+Author: EaseCation
+License: MIT
+Keywords: ecapi,easecation,sdk,python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# ecapi-sdk (Python)
+
+ECAPI 的 Python SDK，封装了常用接口，并内置两种鉴权方式：
+
+- `X-API-Key`（IAM API Key）
+- `X-App-Session-Token`（App Session Token）
+
+## 安装
+
+```bash
+pip install ecapi-sdk
+```
+
+## 快速开始
+
+```python
+from ecapi_sdk import ECAPIClient
+
+client = ECAPIClient(
+    base_url="https://your-ecapi-host",
+    auth={"type": "apiKey", "apiKey": "ec_xxx"},
+)
+
+me = client.user.get_me()
+player = client.player.get_info({"name": "player123"})
+```
+
+切换为 App Session Token：
+
+```python
+client.set_app_session_token("your_app_session_token")
+```
+
+## 客户端能力
+
+- 统一请求入口：`client.request(method, path, ...)`
+- 默认超时：15 秒（`timeout_seconds` 可覆盖）
+- 支持 per-request 覆盖鉴权：`auth=...`
+- 非 2xx 响应抛出 `ECAPIError`（包含 `status`、`payload`、`url`）
+
+## API 覆盖
+
+> SDK 已封装主要高频接口；其余接口可用 `client.request(...)` 直调。
+
+### 用户
+
+- `client.user.get_me()` → `GET /user/me`
+- `client.user.login_by_password(payload)` → `POST /user/auth`
+- `client.user.login_by_oauth2(payload)` → `POST /user/oauth2`
+- `client.user.refresh_token(payload)` → `POST /user/refresh`
+- `client.user.get_openid()` → `GET /user/openid`
+- `client.user.list_all()` → `GET /user/all`
+- `client.user.update_permissions(payload)` → `PUT /user/permissions`
+- `client.user.get_by_id(id)` → `GET /user/:id`
+
+### 玩家
+
+- `client.player.get_info()` / `search_ecid()` / `get_user_data()` / `query_netease()`
+- `client.player.set_rank_level(payload)` / `clear_respack_cache()`
+- `client.player.get_wallet()` / `list_gaming_tags()` / `operate_gaming_tag(payload)`
+- `client.player.get_last_played()` / `get_stage_record()`
+- `client.player.get_headicon()` / `get_skin()`（返回 `bytes`）
+- `client.player.batch_netease_nicknames(payload)`
+- `client.player.get_binding()` / `reset_binding(payload)` / `update_binding(payload)`
+- `client.player.update_user_data(nick, payload)`
+- `client.player.update_password(ecid, payload)` / `get_password_hash(ecid)`
+
+#### 玩家子模块
+
+- `client.player.score.*` → `/player/score*`
+- `client.player.tasks.*` → `/player/:ecid/tasks*`
+- `client.player.merchandise.*` → `/player/:ecid/merchandise*`
+- `client.player.year_summary.*` → `/player/year-summary/*`
+- `client.player.vote.process_rewards()` → `GET /player/vote`
+
+### 管理与处罚
+
+- `client.admin.*` → `/admin/*`
+- `client.punish.*` → `/punish/*`
+- `client.ban.*` → `/ban/*`
+- `client.permission.*` → `/permission`
+
+### 日志与审计
+
+- `client.log.*` → `/log/*`
+- `client.audit.*` → `/audit/*`
+
+### 配置与内容
+
+- `client.stage.*`（含 `stage.logs.*`）→ `/stage/*`
+- `client.item.get_commodity()` → `/item/commodity`
+- `client.cfglang.*` → `/cfglang*`
+- `client.globalkv.*` → `/globalkv*`
+- `client.broadcast.*` → `/broadcast*`
+- `client.pull_config.pull()` → `/pull-config`
+
+### 运营与系统
+
+- `client.order.*` → `/order/*`
+- `client.count.*` → `/count/*`
+- `client.servers.*` → `/servers*`
+- `client.lobby.list()` → `/lobby/list`
+- `client.easechat.*` → `/easechat/*`
+- `client.monitor.spam_detector.*` → `/monitor/spam-detector/*`
+- `client.system.get_health()` → `/health`
+

ecapi_sdk-0.1.0/README.md

@@ -0,0 +1,106 @@
+# ecapi-sdk (Python)
+
+ECAPI 的 Python SDK，封装了常用接口，并内置两种鉴权方式：
+
+- `X-API-Key`（IAM API Key）
+- `X-App-Session-Token`（App Session Token）
+
+## 安装
+
+```bash
+pip install ecapi-sdk
+```
+
+## 快速开始
+
+```python
+from ecapi_sdk import ECAPIClient
+
+client = ECAPIClient(
+    base_url="https://your-ecapi-host",
+    auth={"type": "apiKey", "apiKey": "ec_xxx"},
+)
+
+me = client.user.get_me()
+player = client.player.get_info({"name": "player123"})
+```
+
+切换为 App Session Token：
+
+```python
+client.set_app_session_token("your_app_session_token")
+```
+
+## 客户端能力
+
+- 统一请求入口：`client.request(method, path, ...)`
+- 默认超时：15 秒（`timeout_seconds` 可覆盖）
+- 支持 per-request 覆盖鉴权：`auth=...`
+- 非 2xx 响应抛出 `ECAPIError`（包含 `status`、`payload`、`url`）
+
+## API 覆盖
+
+> SDK 已封装主要高频接口；其余接口可用 `client.request(...)` 直调。
+
+### 用户
+
+- `client.user.get_me()` → `GET /user/me`
+- `client.user.login_by_password(payload)` → `POST /user/auth`
+- `client.user.login_by_oauth2(payload)` → `POST /user/oauth2`
+- `client.user.refresh_token(payload)` → `POST /user/refresh`
+- `client.user.get_openid()` → `GET /user/openid`
+- `client.user.list_all()` → `GET /user/all`
+- `client.user.update_permissions(payload)` → `PUT /user/permissions`
+- `client.user.get_by_id(id)` → `GET /user/:id`
+
+### 玩家
+
+- `client.player.get_info()` / `search_ecid()` / `get_user_data()` / `query_netease()`
+- `client.player.set_rank_level(payload)` / `clear_respack_cache()`
+- `client.player.get_wallet()` / `list_gaming_tags()` / `operate_gaming_tag(payload)`
+- `client.player.get_last_played()` / `get_stage_record()`
+- `client.player.get_headicon()` / `get_skin()`（返回 `bytes`）
+- `client.player.batch_netease_nicknames(payload)`
+- `client.player.get_binding()` / `reset_binding(payload)` / `update_binding(payload)`
+- `client.player.update_user_data(nick, payload)`
+- `client.player.update_password(ecid, payload)` / `get_password_hash(ecid)`
+
+#### 玩家子模块
+
+- `client.player.score.*` → `/player/score*`
+- `client.player.tasks.*` → `/player/:ecid/tasks*`
+- `client.player.merchandise.*` → `/player/:ecid/merchandise*`
+- `client.player.year_summary.*` → `/player/year-summary/*`
+- `client.player.vote.process_rewards()` → `GET /player/vote`
+
+### 管理与处罚
+
+- `client.admin.*` → `/admin/*`
+- `client.punish.*` → `/punish/*`
+- `client.ban.*` → `/ban/*`
+- `client.permission.*` → `/permission`
+
+### 日志与审计
+
+- `client.log.*` → `/log/*`
+- `client.audit.*` → `/audit/*`
+
+### 配置与内容
+
+- `client.stage.*`（含 `stage.logs.*`）→ `/stage/*`
+- `client.item.get_commodity()` → `/item/commodity`
+- `client.cfglang.*` → `/cfglang*`
+- `client.globalkv.*` → `/globalkv*`
+- `client.broadcast.*` → `/broadcast*`
+- `client.pull_config.pull()` → `/pull-config`
+
+### 运营与系统
+
+- `client.order.*` → `/order/*`
+- `client.count.*` → `/count/*`
+- `client.servers.*` → `/servers*`
+- `client.lobby.list()` → `/lobby/list`
+- `client.easechat.*` → `/easechat/*`
+- `client.monitor.spam_detector.*` → `/monitor/spam-detector/*`
+- `client.system.get_health()` → `/health`
+

ecapi_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ecapi-sdk"
+version = "0.1.0"
+description = "ECAPI SDK for Python"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+  { name = "EaseCation" }
+]
+keywords = ["ecapi", "easecation", "sdk", "python"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent"
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ecapi_sdk = ["py.typed"]
+

ecapi_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ecapi_sdk-0.1.0/src/ecapi_sdk/__init__.py

@@ -0,0 +1,4 @@
+from .client import ECAPIClient, ECAPIError
+
+__all__ = ["ECAPIClient", "ECAPIError"]
+

ecapi_sdk-0.1.0/src/ecapi_sdk/client.py

@@ -0,0 +1,794 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Dict, Mapping, Optional, Sequence, Tuple, Union
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlencode
+from urllib.request import Request, urlopen
+
+Primitive = Union[str, int, float, bool, None]
+QueryValue = Union[Primitive, Sequence[Primitive]]
+QueryParams = Mapping[str, QueryValue]
+Headers = Dict[str, str]
+
+AuthCredentials = Dict[str, str]
+UNSET = object()
+
+
+class ECAPIError(Exception):
+    def __init__(self, message: str, status: int, payload: Any, url: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.payload = payload
+        self.url = url
+
+
+def _normalize_base_url(base_url: str) -> str:
+    return base_url[:-1] if base_url.endswith("/") else base_url
+
+
+def _to_query_pairs(query: Optional[QueryParams]) -> Sequence[Tuple[str, str]]:
+    if not query:
+        return []
+
+    pairs = []
+    for key, raw_value in query.items():
+        if raw_value is None:
+            continue
+
+        if isinstance(raw_value, (list, tuple)):
+            for item in raw_value:
+                if item is not None:
+                    pairs.append((key, str(item)))
+            continue
+
+        pairs.append((key, str(raw_value)))
+    return pairs
+
+
+def _parse_body(raw: bytes, content_type: str, response_type: str) -> Any:
+    if response_type == "bytes":
+        return raw
+
+    text = raw.decode("utf-8", errors="replace")
+    if response_type == "text":
+        return text
+
+    if not raw:
+        return None
+
+    if "application/json" in content_type:
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            return text
+
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return text
+
+
+class _HttpClient:
+    def __init__(
+        self,
+        base_url: str,
+        auth: Optional[AuthCredentials] = None,
+        timeout_seconds: float = 15.0,
+        default_headers: Optional[Headers] = None,
+    ) -> None:
+        self._base_url = _normalize_base_url(base_url)
+        self._auth = auth
+        self._timeout_seconds = timeout_seconds
+        self._default_headers = default_headers or {}
+
+    def set_auth(self, auth: Optional[AuthCredentials]) -> None:
+        self._auth = auth
+
+    def clear_auth(self) -> None:
+        self._auth = None
+
+    def set_api_key(self, api_key: str) -> None:
+        self._auth = {"type": "apiKey", "apiKey": api_key}
+
+    def set_app_session_token(self, app_session_token: str) -> None:
+        self._auth = {"type": "appSessionToken", "appSessionToken": app_session_token}
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[QueryParams] = None,
+        body: Any = None,
+        headers: Optional[Headers] = None,
+        response_type: str = "json",
+        auth: Any = UNSET,
+    ) -> Any:
+        request_path = path if path.startswith("/") else f"/{path}"
+        query_pairs = _to_query_pairs(query)
+        query_string = f"?{urlencode(query_pairs, doseq=True)}" if query_pairs else ""
+        url = f"{self._base_url}{request_path}{query_string}"
+
+        merged_headers: Headers = {"Accept": "application/json"}
+        merged_headers.update(self._default_headers)
+        if headers:
+            merged_headers.update(headers)
+
+        resolved_auth = self._auth if auth is UNSET else auth
+        if resolved_auth:
+            auth_type = resolved_auth.get("type")
+            if auth_type == "apiKey":
+                merged_headers["X-API-Key"] = resolved_auth["apiKey"]
+            elif auth_type == "appSessionToken":
+                merged_headers["X-App-Session-Token"] = resolved_auth["appSessionToken"]
+
+        request_data: Optional[bytes] = None
+        if body is not None:
+            content_type = merged_headers.get("Content-Type", "")
+            if not content_type:
+                merged_headers["Content-Type"] = "application/json"
+                content_type = "application/json"
+
+            if "application/json" in content_type and not isinstance(body, (str, bytes, bytearray)):
+                request_data = json.dumps(body).encode("utf-8")
+            elif isinstance(body, bytes):
+                request_data = body
+            elif isinstance(body, bytearray):
+                request_data = bytes(body)
+            else:
+                request_data = str(body).encode("utf-8")
+
+        req = Request(url=url, data=request_data, method=method.upper(), headers=merged_headers)
+
+        try:
+            with urlopen(req, timeout=self._timeout_seconds) as response:
+                raw = response.read()
+                content_type = response.headers.get("Content-Type", "")
+                if response.status == 204:
+                    return None
+                return _parse_body(raw, content_type, response_type)
+        except HTTPError as error:
+            raw = error.read() if hasattr(error, "read") else b""
+            content_type = error.headers.get("Content-Type", "") if error.headers else ""
+            payload = _parse_body(raw, content_type, response_type) if raw else None
+            raise ECAPIError(
+                f"Request failed with status {error.code}",
+                error.code,
+                payload,
+                url,
+            ) from error
+        except URLError as error:
+            raise ECAPIError("Network request failed", 0, str(error.reason), url) from error
+        except TimeoutError as error:
+            raise ECAPIError("Request timeout", 0, None, url) from error
+
+
+class _BaseApi:
+    def __init__(self, http: _HttpClient) -> None:
+        self._http = http
+
+    def _get(self, path: str, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._http.request("GET", path, query=query, **kwargs)
+
+    def _post(self, path: str, body: Any = None, **kwargs: Any) -> Any:
+        return self._http.request("POST", path, body=body, **kwargs)
+
+    def _put(self, path: str, body: Any = None, **kwargs: Any) -> Any:
+        return self._http.request("PUT", path, body=body, **kwargs)
+
+    def _patch(self, path: str, body: Any = None, **kwargs: Any) -> Any:
+        return self._http.request("PATCH", path, body=body, **kwargs)
+
+    def _delete(
+        self,
+        path: str,
+        query: Optional[QueryParams] = None,
+        body: Any = None,
+        **kwargs: Any,
+    ) -> Any:
+        return self._http.request("DELETE", path, query=query, body=body, **kwargs)
+
+
+class UserAPI(_BaseApi):
+    def get_me(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/user/me", query, **kwargs)
+
+    def login_by_password(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/user/auth", payload, **kwargs)
+
+    def login_by_oauth2(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/user/oauth2", payload, **kwargs)
+
+    def refresh_token(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/user/refresh", payload, **kwargs)
+
+    def get_openid(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/user/openid", query, **kwargs)
+
+    def list_all(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/user/all", query, **kwargs)
+
+    def update_permissions(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._put("/user/permissions", payload, **kwargs)
+
+    def get_by_id(self, user_id: str, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get(f"/user/{quote(user_id, safe='')}", query, **kwargs)
+
+
+class PlayerScoreAPI(_BaseApi):
+    def get_score(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/score", query, **kwargs)
+
+    def get_stages(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/score/stages", query, **kwargs)
+
+    def get_top(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/score/top", query, **kwargs)
+
+    def delete_top(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._delete("/player/score/top", query=query, **kwargs)
+
+    def get_config(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/score/config", query, **kwargs)
+
+    def get_leaderboard(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/score/leaderboard", query, **kwargs)
+
+
+class PlayerTasksAPI(_BaseApi):
+    def list(self, ecid: str, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get(f"/player/{quote(ecid, safe='')}/tasks", query, **kwargs)
+
+    def create(self, ecid: str, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post(f"/player/{quote(ecid, safe='')}/tasks", payload, **kwargs)
+
+    def update(self, ecid: str, task_id: str, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._put(
+            f"/player/{quote(ecid, safe='')}/tasks/{quote(task_id, safe='')}",
+            payload,
+            **kwargs,
+        )
+
+    def delete_one(
+        self, ecid: str, task_id: str, query: Optional[QueryParams] = None, **kwargs: Any
+    ) -> Any:
+        return self._delete(
+            f"/player/{quote(ecid, safe='')}/tasks/{quote(task_id, safe='')}",
+            query=query,
+            **kwargs,
+        )
+
+
+class PlayerMerchandiseAPI(_BaseApi):
+    def list(self, ecid: str, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get(f"/player/{quote(ecid, safe='')}/merchandise", query, **kwargs)
+
+    def create(self, ecid: str, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post(f"/player/{quote(ecid, safe='')}/merchandise", payload, **kwargs)
+
+    def update(self, ecid: str, id_item: str, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._put(
+            f"/player/{quote(ecid, safe='')}/merchandise/{quote(id_item, safe='')}",
+            payload,
+            **kwargs,
+        )
+
+    def delete_one(
+        self, ecid: str, id_item: str, query: Optional[QueryParams] = None, **kwargs: Any
+    ) -> Any:
+        return self._delete(
+            f"/player/{quote(ecid, safe='')}/merchandise/{quote(id_item, safe='')}",
+            query=query,
+            **kwargs,
+        )
+
+
+class PlayerYearSummaryAPI(_BaseApi):
+    def get_basic_info(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/year-summary/basic-info", query, **kwargs)
+
+    def get_login_stats(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/year-summary/login-stats", query, **kwargs)
+
+    def get_game_stats(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/year-summary/game-stats", query, **kwargs)
+
+    def get_rank_data(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/year-summary/rank-data", query, **kwargs)
+
+    def get_currency_data(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/year-summary/currency-data", query, **kwargs)
+
+    def get_social_data(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/year-summary/social-data", query, **kwargs)
+
+
+class PlayerVoteAPI(_BaseApi):
+    def process_rewards(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/vote", query, **kwargs)
+
+
+class PlayerAPI(_BaseApi):
+    def __init__(self, http: _HttpClient) -> None:
+        super().__init__(http)
+        self.score = PlayerScoreAPI(http)
+        self.tasks = PlayerTasksAPI(http)
+        self.merchandise = PlayerMerchandiseAPI(http)
+        self.year_summary = PlayerYearSummaryAPI(http)
+        self.vote = PlayerVoteAPI(http)
+
+    def get_info(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/info", query, **kwargs)
+
+    def search_ecid(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/searchecid", query, **kwargs)
+
+    def get_user_data(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/userdata", query, **kwargs)
+
+    def query_netease(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/querynetease", query, **kwargs)
+
+    def set_rank_level(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/player/ranklevel", payload, **kwargs)
+
+    def clear_respack_cache(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._delete("/player/respack/cache", query=query, **kwargs)
+
+    def get_wallet(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/wallet", query, **kwargs)
+
+    def list_gaming_tags(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/gaming-tag", query, **kwargs)
+
+    def operate_gaming_tag(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/player/gaming-tag", payload, **kwargs)
+
+    def get_last_played(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/last-played", query, **kwargs)
+
+    def get_stage_record(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/stage/record", query, **kwargs)
+
+    def get_headicon(self, query: Optional[QueryParams] = None, **kwargs: Any) -> bytes:
+        return self._http.request(
+            "GET",
+            "/player/headicon",
+            query=query,
+            response_type="bytes",
+            **kwargs,
+        )
+
+    def get_skin(self, query: Optional[QueryParams] = None, **kwargs: Any) -> bytes:
+        return self._http.request(
+            "GET",
+            "/player/skin",
+            query=query,
+            response_type="bytes",
+            **kwargs,
+        )
+
+    def batch_netease_nicknames(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/player/neteasenicknames", payload, **kwargs)
+
+    def get_binding(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/player/binding", query, **kwargs)
+
+    def reset_binding(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/player/reset-binding", payload, **kwargs)
+
+    def update_binding(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/player/update-binding", payload, **kwargs)
+
+    def update_user_data(self, nick: str, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post(f"/player/update/{quote(nick, safe='')}", payload, **kwargs)
+
+    def update_password(self, ecid: str, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post(f"/player/password/{quote(ecid, safe='')}", payload, **kwargs)
+
+    def get_password_hash(
+        self, ecid: str, query: Optional[QueryParams] = None, **kwargs: Any
+    ) -> Any:
+        return self._get(f"/player/password/{quote(ecid, safe='')}", query, **kwargs)
+
+
+class AdminAPI(_BaseApi):
+    def send_mail(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/admin/mail", payload, **kwargs)
+
+    def prism_device_ban(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/admin/prism-device-ban", payload, **kwargs)
+
+    def get_prism_device_ban_log(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/admin/prism-device-ban-log", query, **kwargs)
+
+    def upsert_overwatch_case(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/admin/overwatch", payload, **kwargs)
+
+    def get_overwatch_case(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/admin/overwatch", query, **kwargs)
+
+    def get_operation_logs(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/admin/operation", query, **kwargs)
+
+    def get_operation_statistics(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/admin/operation/statistic", query, **kwargs)
+
+
+class PunishAPI(_BaseApi):
+    def hack(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/punish/hack", payload, **kwargs)
+
+    def ban(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/punish/ban", payload, **kwargs)
+
+    def unban(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/punish/unban", payload, **kwargs)
+
+    def mute(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/punish/mute", payload, **kwargs)
+
+    def unmute(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/punish/unmute", payload, **kwargs)
+
+    def warn(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/punish/warn", payload, **kwargs)
+
+    def kick(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/punish/kick", payload, **kwargs)
+
+    def clear_degree(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/punish/clear-degree", payload, **kwargs)
+
+    def overwatch(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/punish/overwatch", payload, **kwargs)
+
+
+class BanAPI(_BaseApi):
+    def ban(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/ban", payload, **kwargs)
+
+    def clear_degree(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/ban/clear-degree", payload, **kwargs)
+
+    def parkour_punish(
+        self,
+        query: Optional[QueryParams] = None,
+        payload: Optional[Mapping[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Any:
+        return self._http.request("POST", "/ban/parkour-punish", query=query, body=payload, **kwargs)
+
+
+class PermissionAPI(_BaseApi):
+    def get(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/permission", query, **kwargs)
+
+    def upsert(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/permission", payload, **kwargs)
+
+    def delete_one(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._delete("/permission", query=query, **kwargs)
+
+
+class LogAPI(_BaseApi):
+    def get_action(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/log/action", query, **kwargs)
+
+    def get_chat(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/log/chat", query, **kwargs)
+
+    def get_auth(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/log/auth", query, **kwargs)
+
+    def get_teaming(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/log/teaming", query, **kwargs)
+
+    def get_latest_teaming(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/log/latestTeaming", query, **kwargs)
+
+    def get_command(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/log/command", query, **kwargs)
+
+    def get_mail(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/log/mail", query, **kwargs)
+
+
+class OrderAPI(_BaseApi):
+    def get_deliver(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/order/deliver", query, **kwargs)
+
+    def get_logs(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/order/logs", query, **kwargs)
+
+    def get_exchange_logs(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/order/exchange-logs", query, **kwargs)
+
+    def get_download_count(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/order/download/count", query, **kwargs)
+
+    def create_download_task(
+        self,
+        query: Optional[QueryParams] = None,
+        payload: Optional[Mapping[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Any:
+        return self._http.request("POST", "/order/download/create", query=query, body=payload, **kwargs)
+
+    def get_download_status(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/order/download/status", query, **kwargs)
+
+    def list_download_tasks(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/order/download/list", query, **kwargs)
+
+
+class StageLogAPI(_BaseApi):
+    def list(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/stage/log/list", query, **kwargs)
+
+    def query(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/stage/log/query", query, **kwargs)
+
+
+class StageAPI(_BaseApi):
+    def __init__(self, http: _HttpClient) -> None:
+        super().__init__(http)
+        self.logs = StageLogAPI(http)
+
+    def get_types(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/stage/types", query, **kwargs)
+
+    def create(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/stage/create", payload, **kwargs)
+
+    def get_info(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/stage/info", query, **kwargs)
+
+    def get_db_id(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/stage/db-id", query, **kwargs)
+
+
+class ItemAPI(_BaseApi):
+    def get_commodity(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/item/commodity", query, **kwargs)
+
+
+class CountAPI(_BaseApi):
+    def get_history(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/count/history", query, **kwargs)
+
+    def get_latest(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/count/latest", query, **kwargs)
+
+    def get_types(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/count/types", query, **kwargs)
+
+
+class ServersAPI(_BaseApi):
+    def list(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/servers", query, **kwargs)
+
+    def get_statistics(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/servers/statistics", query, **kwargs)
+
+    def get_mainstack_event(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/servers/mainstack-event", query, **kwargs)
+
+
+class LobbyAPI(_BaseApi):
+    def list(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/lobby/list", query, **kwargs)
+
+
+class CfgLangAPI(_BaseApi):
+    def list(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/cfglang", query, **kwargs)
+
+    def compare(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/cfglang/compare", query, **kwargs)
+
+    def deploy(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/cfglang/deploy", payload, **kwargs)
+
+    def create(
+        self, query: Optional[QueryParams], payload: Mapping[str, Any], **kwargs: Any
+    ) -> Any:
+        return self._http.request("POST", "/cfglang", query=query, body=payload, **kwargs)
+
+    def update(
+        self, query: Optional[QueryParams], payload: Mapping[str, Any], **kwargs: Any
+    ) -> Any:
+        return self._http.request("PATCH", "/cfglang", query=query, body=payload, **kwargs)
+
+    def delete_one(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._delete("/cfglang", query=query, **kwargs)
+
+
+class GlobalKVAPI(_BaseApi):
+    def list(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/globalkv", query, **kwargs)
+
+    def get_one(self, key: str, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get(f"/globalkv/{quote(key, safe='')}", query, **kwargs)
+
+    def create(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/globalkv", payload, **kwargs)
+
+    def update(self, key: str, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._put(f"/globalkv/{quote(key, safe='')}", payload, **kwargs)
+
+    def delete_one(self, key: str, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._delete(f"/globalkv/{quote(key, safe='')}", query=query, **kwargs)
+
+    def delete_batch(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._delete("/globalkv", body=payload, **kwargs)
+
+
+class BroadcastAPI(_BaseApi):
+    def list(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/broadcast", query, **kwargs)
+
+    def compare(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/broadcast/compare", query, **kwargs)
+
+    def deploy(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/broadcast/deploy", payload, **kwargs)
+
+    def get_one(self, msg: str, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get(f"/broadcast/{quote(msg, safe='')}", query, **kwargs)
+
+    def create(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/broadcast", payload, **kwargs)
+
+    def update(self, msg: str, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._put(f"/broadcast/{quote(msg, safe='')}", payload, **kwargs)
+
+    def delete_one(self, msg: str, payload: Optional[Mapping[str, Any]] = None, **kwargs: Any) -> Any:
+        return self._delete(f"/broadcast/{quote(msg, safe='')}", body=payload, **kwargs)
+
+
+class EaseChatAPI(_BaseApi):
+    def send_hlaba(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/easechat/hlaba", payload, **kwargs)
+
+    def list_subscriptions(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/easechat/subscriptions", query, **kwargs)
+
+    def create_subscription(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/easechat/subscriptions", payload, **kwargs)
+
+    def delete_subscription(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._delete("/easechat/subscriptions", query=query, **kwargs)
+
+
+class AuditAPI(_BaseApi):
+    def get_auth_logs(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/audit/auth", query, **kwargs)
+
+    def get_player_logs(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/audit/player", query, **kwargs)
+
+    def get_punishment_logs(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/audit/punishment", query, **kwargs)
+
+    def get_permission_logs(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/audit/permission", query, **kwargs)
+
+    def get_admin_logs(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/audit/admin", query, **kwargs)
+
+    def get_config_logs(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/audit/config", query, **kwargs)
+
+
+class SpamDetectorAPI(_BaseApi):
+    def get_status(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/monitor/spam-detector/status", query, **kwargs)
+
+    def control(self, payload: Mapping[str, Any], **kwargs: Any) -> Any:
+        return self._post("/monitor/spam-detector/control", payload, **kwargs)
+
+    def get_stats(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/monitor/spam-detector/stats", query, **kwargs)
+
+
+class MonitorAPI(_BaseApi):
+    def __init__(self, http: _HttpClient) -> None:
+        super().__init__(http)
+        self.spam_detector = SpamDetectorAPI(http)
+
+
+class PullConfigAPI(_BaseApi):
+    def pull(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/pull-config", query, **kwargs)
+
+
+class SystemAPI(_BaseApi):
+    def get_root(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/", query, response_type="text", **kwargs)
+
+    def get_health(self, query: Optional[QueryParams] = None, **kwargs: Any) -> Any:
+        return self._get("/health", query, **kwargs)
+
+
+@dataclass
+class ClientOptions:
+    base_url: str
+    auth: Optional[AuthCredentials] = None
+    timeout_seconds: float = 15.0
+    default_headers: Optional[Headers] = None
+
+
+class ECAPIClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        auth: Optional[AuthCredentials] = None,
+        timeout_seconds: float = 15.0,
+        default_headers: Optional[Headers] = None,
+    ) -> None:
+        self._http = _HttpClient(
+            base_url=base_url,
+            auth=auth,
+            timeout_seconds=timeout_seconds,
+            default_headers=default_headers,
+        )
+
+        self.user = UserAPI(self._http)
+        self.player = PlayerAPI(self._http)
+        self.admin = AdminAPI(self._http)
+        self.punish = PunishAPI(self._http)
+        self.ban = BanAPI(self._http)
+        self.permission = PermissionAPI(self._http)
+        self.log = LogAPI(self._http)
+        self.order = OrderAPI(self._http)
+        self.stage = StageAPI(self._http)
+        self.item = ItemAPI(self._http)
+        self.count = CountAPI(self._http)
+        self.servers = ServersAPI(self._http)
+        self.lobby = LobbyAPI(self._http)
+        self.cfglang = CfgLangAPI(self._http)
+        self.globalkv = GlobalKVAPI(self._http)
+        self.broadcast = BroadcastAPI(self._http)
+        self.easechat = EaseChatAPI(self._http)
+        self.audit = AuditAPI(self._http)
+        self.monitor = MonitorAPI(self._http)
+        self.pull_config = PullConfigAPI(self._http)
+        self.system = SystemAPI(self._http)
+
+    def set_auth(self, auth: Optional[AuthCredentials]) -> None:
+        self._http.set_auth(auth)
+
+    def set_api_key(self, api_key: str) -> None:
+        self._http.set_api_key(api_key)
+
+    def set_app_session_token(self, app_session_token: str) -> None:
+        self._http.set_app_session_token(app_session_token)
+
+    def clear_auth(self) -> None:
+        self._http.clear_auth()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[QueryParams] = None,
+        body: Any = None,
+        headers: Optional[Headers] = None,
+        response_type: str = "json",
+        auth: Any = UNSET,
+    ) -> Any:
+        return self._http.request(
+            method,
+            path,
+            query=query,
+            body=body,
+            headers=headers,
+            response_type=response_type,
+            auth=auth,
+        )
+

ecapi_sdk-0.1.0/src/ecapi_sdk/py.typed

@@ -0,0 +1 @@
+

ecapi_sdk-0.1.0/src/ecapi_sdk.egg-info/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: ecapi-sdk
+Version: 0.1.0
+Summary: ECAPI SDK for Python
+Author: EaseCation
+License: MIT
+Keywords: ecapi,easecation,sdk,python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# ecapi-sdk (Python)
+
+ECAPI 的 Python SDK，封装了常用接口，并内置两种鉴权方式：
+
+- `X-API-Key`（IAM API Key）
+- `X-App-Session-Token`（App Session Token）
+
+## 安装
+
+```bash
+pip install ecapi-sdk
+```
+
+## 快速开始
+
+```python
+from ecapi_sdk import ECAPIClient
+
+client = ECAPIClient(
+    base_url="https://your-ecapi-host",
+    auth={"type": "apiKey", "apiKey": "ec_xxx"},
+)
+
+me = client.user.get_me()
+player = client.player.get_info({"name": "player123"})
+```
+
+切换为 App Session Token：
+
+```python
+client.set_app_session_token("your_app_session_token")
+```
+
+## 客户端能力
+
+- 统一请求入口：`client.request(method, path, ...)`
+- 默认超时：15 秒（`timeout_seconds` 可覆盖）
+- 支持 per-request 覆盖鉴权：`auth=...`
+- 非 2xx 响应抛出 `ECAPIError`（包含 `status`、`payload`、`url`）
+
+## API 覆盖
+
+> SDK 已封装主要高频接口；其余接口可用 `client.request(...)` 直调。
+
+### 用户
+
+- `client.user.get_me()` → `GET /user/me`
+- `client.user.login_by_password(payload)` → `POST /user/auth`
+- `client.user.login_by_oauth2(payload)` → `POST /user/oauth2`
+- `client.user.refresh_token(payload)` → `POST /user/refresh`
+- `client.user.get_openid()` → `GET /user/openid`
+- `client.user.list_all()` → `GET /user/all`
+- `client.user.update_permissions(payload)` → `PUT /user/permissions`
+- `client.user.get_by_id(id)` → `GET /user/:id`
+
+### 玩家
+
+- `client.player.get_info()` / `search_ecid()` / `get_user_data()` / `query_netease()`
+- `client.player.set_rank_level(payload)` / `clear_respack_cache()`
+- `client.player.get_wallet()` / `list_gaming_tags()` / `operate_gaming_tag(payload)`
+- `client.player.get_last_played()` / `get_stage_record()`
+- `client.player.get_headicon()` / `get_skin()`（返回 `bytes`）
+- `client.player.batch_netease_nicknames(payload)`
+- `client.player.get_binding()` / `reset_binding(payload)` / `update_binding(payload)`
+- `client.player.update_user_data(nick, payload)`
+- `client.player.update_password(ecid, payload)` / `get_password_hash(ecid)`
+
+#### 玩家子模块
+
+- `client.player.score.*` → `/player/score*`
+- `client.player.tasks.*` → `/player/:ecid/tasks*`
+- `client.player.merchandise.*` → `/player/:ecid/merchandise*`
+- `client.player.year_summary.*` → `/player/year-summary/*`
+- `client.player.vote.process_rewards()` → `GET /player/vote`
+
+### 管理与处罚
+
+- `client.admin.*` → `/admin/*`
+- `client.punish.*` → `/punish/*`
+- `client.ban.*` → `/ban/*`
+- `client.permission.*` → `/permission`
+
+### 日志与审计
+
+- `client.log.*` → `/log/*`
+- `client.audit.*` → `/audit/*`
+
+### 配置与内容
+
+- `client.stage.*`（含 `stage.logs.*`）→ `/stage/*`
+- `client.item.get_commodity()` → `/item/commodity`
+- `client.cfglang.*` → `/cfglang*`
+- `client.globalkv.*` → `/globalkv*`
+- `client.broadcast.*` → `/broadcast*`
+- `client.pull_config.pull()` → `/pull-config`
+
+### 运营与系统
+
+- `client.order.*` → `/order/*`
+- `client.count.*` → `/count/*`
+- `client.servers.*` → `/servers*`
+- `client.lobby.list()` → `/lobby/list`
+- `client.easechat.*` → `/easechat/*`
+- `client.monitor.spam_detector.*` → `/monitor/spam-detector/*`
+- `client.system.get_health()` → `/health`
+

ecapi_sdk-0.1.0/src/ecapi_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+src/ecapi_sdk/__init__.py
+src/ecapi_sdk/client.py
+src/ecapi_sdk/py.typed
+src/ecapi_sdk.egg-info/PKG-INFO
+src/ecapi_sdk.egg-info/SOURCES.txt
+src/ecapi_sdk.egg-info/dependency_links.txt
+src/ecapi_sdk.egg-info/top_level.txt

ecapi_sdk-0.1.0/src/ecapi_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ecapi_sdk-0.1.0/src/ecapi_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+ecapi_sdk