ecapi-sdk 0.1.3
ECAPI SDK for Python
License: MIT
Requires Python: >=3.9
Keywords: ecapi, easecation, sdk, python

# 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(
    auth={"type": "apiKey", "apiKey": "ec_xxx"},
)

me = client.user.get_me()
player = client.player.get_info({"name": "player123"})
wallet = client.player.get_wallet(ecid="player-ecid")
```

切换为 App Session Token：

```python
client.set_app_session_token("your_app_session_token")
```

## 客户端能力

- 默认 `base_url`：`https://console.easecation.net/apiv2`
- 统一请求入口：`client.request(method, path, ...)`
- 默认超时：15 秒（`timeout_seconds` 可覆盖）
- 支持 per-request 覆盖鉴权：`auth=...`
- 非 2xx 响应抛出 `ECAPIError`（包含 `status`、`payload`、`url`）

## 参数传递（必填/可选）

- 所有带查询参数的接口都支持两种写法：
  - 推荐：关键字参数（更直观）`client.player.get_wallet(ecid="...")`
  - 兼容：字典参数 `client.player.get_wallet({"ecid": "..."})`
- 哪些字段必填、哪些可选，请直接看完整参考文档：`API_REFERENCE.md`
- 该参考文档由后端 OpenAPI 自动生成，和服务端校验保持一致

## IDE 强类型提示

- 包内提供 `client.pyi`，IDE 会在悬停和参数填写时显示方法级必填/可选信息
- 查询参数支持两种输入方式：
  - `query` 结构化参数（会有 TypedDict 提示）
  - 关键字参数（例如 `ecid=...`）

## 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`

## 完整 API 参考

- `API_REFERENCE.md`

更新命令（在 `easecation-api` 根目录执行）：

```bash
python3 sdk/generate_sdk_api_reference.py
```