pcs-sdk 0.1.0__tar.gz

pcs_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: pcs-sdk
+Version: 0.1.0
+Summary: pcs API client built on requests
+Author: staugur
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.20
+
+# pcs SDK
+
+pcs 的 Python 客户端，基于 `requests` 封装「费用模块」与「防火墙模块」接口，
+统一处理 HMAC-SHA256 请求签名、JSON 序列化与错误判定。接口字段与错误码见仓库根目录 `API.md`。
+
+## 安装
+
+```bash
+# 方式一：从 PyPI 安装（推荐）
+pip install pcs-sdk
+
+# 方式二：本地开发（可编辑安装）
+cd sdk
+pip install -e .
+
+# 方式三：直接安装 GitHub 仓库中的 sdk 子目录
+pip install "git+https://github.com/staugur/pcs.git#subdirectory=sdk"
+```
+
+## 版本号与发布
+
+版本号由 `setuptools_scm` 从 git 自动派生，**无需手改** `pcs/__init__.py` 里的
+`__version__`：
+
+- 打了 `v*` tag（如 `v0.1.0`）并推送 → 正式版 `0.1.0`；
+- 推送改动落到 `sdk/` 目录（仅 `master` / `dev` 分支）→ 自动发布开发版，版本号形如
+  `0.1.0.dev12+gabcdef`（距最近 tag 的提交数 + commit sha，天然唯一、不撞车）；
+- 在 Actions 页手动 Run workflow → 开发版 `0.1.0.dev<时间戳>`（精确到秒，天然唯一、
+  可直发 PyPI）。
+
+> 仅 `sdk/` 目录的改动会触发自动发布；改 `src/`、`AGENTS.md`、`API.md` 等其他目录
+> 不会触发，避免无关改动误发版本。同一 push 若同时命中多个触发条件（如打了 `v*` tag
+> 且其提交刚好改了 `sdk/`），工作流只运行一次。
+
+发布由仓库的 GitHub Action（`.github/workflows/publish.yml`）完成：
+
+- 推送 `v*` tag → 自动发布正式版到 PyPI；
+- 推送改动落到 `sdk/**`（仅 `master` / `dev`）→ 自动发布开发版；
+- 在 Actions 页手动 Run workflow → 快速发布开发版（无需打 tag）。
+
+> 采用 OIDC trusted publishing（免密钥）：首次发布前需在 PyPI 的 `pcs-sdk` 项目配置
+> Trusted Publisher（Owner=`staugur`、Repository name=`pcs`、Workflow name=`publish.yml`、
+> Environment name 留空），无需配置 `PYPI_API_TOKEN`。
+
+## 快速上手
+
+```python
+from pcs import PcsClient
+
+client = PcsClient("https://pcs.example.com", api_key="<API_KEY>")
+
+# 费用：查询余额（记录不存在返回 None）
+balance = client.fee_balance(uid="u1", module="blog")
+
+# 费用：查询全部模块状态 / 流水 / 付费模块
+client.fee_balances(uid="u1")
+client.fee_logs(uid="u1", module="blog", limit=50)
+client.fee_modules()
+
+# 费用：充值（biz_no 务必幂等——重试复用原值，新动作换新值）
+client.fee_recharge(
+    uid="u1", module="blog", amount=120, pay_type="prepaid",
+    pay_source="alipay", start_at=1790304000, end_at=1821840000,
+    level="pro", trade_no="202609010001",
+    biz_no="blog-2026-09-recharge-001",
+)
+
+# 费用：消费扣减（仅按量付费模块）
+client.fee_consume(uid="u1", module="blog", amount=30,
+                   biz_no="blog-2026-09-usage-001")
+
+# 主机管理：列出已登记主机
+client.host_hosts()
+
+# 防火墙：列出放行记录（按主机过滤 / 分页：limit 上限 200）
+client.host_allows(host_id=1)
+client.host_allows(limit=20, offset=0)
+
+# 防火墙：临时放行（到期时间 expire_at 为 10 位时间戳）
+client.host_allow(host_id=1, ip="1.2.3.4", port="3306",
+                  expire_at=1790304000 + 3600, remark="临时开库")
+
+# 防火墙：撤销放行
+client.host_revoke(allow_id=42)
+
+# nginx 白名单：列出 / 新增 / 撤销（pcs 全权托管 conf，到期自动 reload）
+client.host_nginx_allows(host_id=1)
+client.host_nginx_allow(host_id=1, ip="1.2.3.4",
+                        expire_at=1790304000 + 3600, remark="临时开站")
+client.host_nginx_revoke(allow_id=42)
+```
+
+## 错误处理
+
+接口返回 `success=false` 或 HTTP 错误时抛出 `pcs.PcsApiError`，可读取
+`code`（错误码，如 `PARAM_ERROR` / `INSUFFICIENT_BALANCE` / `IDEMPOTENCY_CONFLICT`）、
+`message` 与 `status_code`：
+
+```python
+from pcs import PcsClient, PcsApiError
+
+try:
+    client.fee_consume(uid="u1", module="blog", amount=999, biz_no="x-1")
+except PcsApiError as e:
+    print(e.code, e.status_code, e.message)
+```
+
+## 复用连接
+
+`PcsClient` 默认内部持有 `requests.Session`（连接池复用）。需要自定义会话
+（代理、证书、重试策略）时传入 `session=` 即可。

pcs_sdk-0.1.0/README.md

@@ -0,0 +1,111 @@
+# pcs SDK
+
+pcs 的 Python 客户端，基于 `requests` 封装「费用模块」与「防火墙模块」接口，
+统一处理 HMAC-SHA256 请求签名、JSON 序列化与错误判定。接口字段与错误码见仓库根目录 `API.md`。
+
+## 安装
+
+```bash
+# 方式一：从 PyPI 安装（推荐）
+pip install pcs-sdk
+
+# 方式二：本地开发（可编辑安装）
+cd sdk
+pip install -e .
+
+# 方式三：直接安装 GitHub 仓库中的 sdk 子目录
+pip install "git+https://github.com/staugur/pcs.git#subdirectory=sdk"
+```
+
+## 版本号与发布
+
+版本号由 `setuptools_scm` 从 git 自动派生，**无需手改** `pcs/__init__.py` 里的
+`__version__`：
+
+- 打了 `v*` tag（如 `v0.1.0`）并推送 → 正式版 `0.1.0`；
+- 推送改动落到 `sdk/` 目录（仅 `master` / `dev` 分支）→ 自动发布开发版，版本号形如
+  `0.1.0.dev12+gabcdef`（距最近 tag 的提交数 + commit sha，天然唯一、不撞车）；
+- 在 Actions 页手动 Run workflow → 开发版 `0.1.0.dev<时间戳>`（精确到秒，天然唯一、
+  可直发 PyPI）。
+
+> 仅 `sdk/` 目录的改动会触发自动发布；改 `src/`、`AGENTS.md`、`API.md` 等其他目录
+> 不会触发，避免无关改动误发版本。同一 push 若同时命中多个触发条件（如打了 `v*` tag
+> 且其提交刚好改了 `sdk/`），工作流只运行一次。
+
+发布由仓库的 GitHub Action（`.github/workflows/publish.yml`）完成：
+
+- 推送 `v*` tag → 自动发布正式版到 PyPI；
+- 推送改动落到 `sdk/**`（仅 `master` / `dev`）→ 自动发布开发版；
+- 在 Actions 页手动 Run workflow → 快速发布开发版（无需打 tag）。
+
+> 采用 OIDC trusted publishing（免密钥）：首次发布前需在 PyPI 的 `pcs-sdk` 项目配置
+> Trusted Publisher（Owner=`staugur`、Repository name=`pcs`、Workflow name=`publish.yml`、
+> Environment name 留空），无需配置 `PYPI_API_TOKEN`。
+
+## 快速上手
+
+```python
+from pcs import PcsClient
+
+client = PcsClient("https://pcs.example.com", api_key="<API_KEY>")
+
+# 费用：查询余额（记录不存在返回 None）
+balance = client.fee_balance(uid="u1", module="blog")
+
+# 费用：查询全部模块状态 / 流水 / 付费模块
+client.fee_balances(uid="u1")
+client.fee_logs(uid="u1", module="blog", limit=50)
+client.fee_modules()
+
+# 费用：充值（biz_no 务必幂等——重试复用原值，新动作换新值）
+client.fee_recharge(
+    uid="u1", module="blog", amount=120, pay_type="prepaid",
+    pay_source="alipay", start_at=1790304000, end_at=1821840000,
+    level="pro", trade_no="202609010001",
+    biz_no="blog-2026-09-recharge-001",
+)
+
+# 费用：消费扣减（仅按量付费模块）
+client.fee_consume(uid="u1", module="blog", amount=30,
+                   biz_no="blog-2026-09-usage-001")
+
+# 主机管理：列出已登记主机
+client.host_hosts()
+
+# 防火墙：列出放行记录（按主机过滤 / 分页：limit 上限 200）
+client.host_allows(host_id=1)
+client.host_allows(limit=20, offset=0)
+
+# 防火墙：临时放行（到期时间 expire_at 为 10 位时间戳）
+client.host_allow(host_id=1, ip="1.2.3.4", port="3306",
+                  expire_at=1790304000 + 3600, remark="临时开库")
+
+# 防火墙：撤销放行
+client.host_revoke(allow_id=42)
+
+# nginx 白名单：列出 / 新增 / 撤销（pcs 全权托管 conf，到期自动 reload）
+client.host_nginx_allows(host_id=1)
+client.host_nginx_allow(host_id=1, ip="1.2.3.4",
+                        expire_at=1790304000 + 3600, remark="临时开站")
+client.host_nginx_revoke(allow_id=42)
+```
+
+## 错误处理
+
+接口返回 `success=false` 或 HTTP 错误时抛出 `pcs.PcsApiError`，可读取
+`code`（错误码，如 `PARAM_ERROR` / `INSUFFICIENT_BALANCE` / `IDEMPOTENCY_CONFLICT`）、
+`message` 与 `status_code`：
+
+```python
+from pcs import PcsClient, PcsApiError
+
+try:
+    client.fee_consume(uid="u1", module="blog", amount=999, biz_no="x-1")
+except PcsApiError as e:
+    print(e.code, e.status_code, e.message)
+```
+
+## 复用连接
+
+`PcsClient` 默认内部持有 `requests.Session`（连接池复用）。需要自定义会话
+（代理、证书、重试策略）时传入 `session=` 即可。

pcs_sdk-0.1.0/pcs/__init__.py

@@ -0,0 +1,34 @@
+"""pcs API 客户端 SDK。
+
+基于 ``requests`` 封装 pcs 的费用模块与主机管理模块接口，统一处理
+HMAC-SHA256 请求签名、JSON 序列化与错误判定。接口细节见仓库根目录 ``API.md``。
+
+典型用法::
+
+    from pcs import PcsClient
+
+    client = PcsClient("https://pcs.example.com", api_key="<API_KEY>")
+
+    balance = client.fee_balance(uid="u1", module="blog")
+    client.fee_recharge(
+        uid="u1", module="blog", amount=120, pay_type="prepaid",
+        pay_source="alipay", start_at=1790304000, end_at=1821840000,
+        level="pro", trade_no="202609010001",
+        biz_no="blog-2026-09-recharge-001",
+    )
+    client.host_allow(host_id=1, ip="1.2.3.4", port="3306",
+                      expire_at=1790304000 + 3600, remark="临时开库")
+    client.host_nginx_allow(host_id=1, ip="1.2.3.4",
+                            expire_at=1790304000 + 3600)
+"""
+
+from .client import PcsApiError, PcsClient
+
+__all__ = ["PcsClient", "PcsApiError"]
+
+try:
+    from importlib.metadata import version as _pkg_version
+
+    __version__ = _pkg_version("pcs-sdk")
+except Exception:  # pragma: no cover - 非安装态（如直接跑源码）回退
+    __version__ = "0.1.0"

pcs_sdk-0.1.0/pcs/client.py

@@ -0,0 +1,390 @@
+"""pcs API 客户端实现。
+
+安全说明
+--------
+``api_key`` 只在客户端本地参与 HMAC-SHA256 签名计算，**绝不**随请求发往服务端；
+网络层只传输签名值 ``X-Signature`` 与时间戳 / nonce，因此密钥本身不会泄露。
+服务端使用相同的 ``API_KEY`` 独立验签，实现请求来源鉴权（详见仓库根 ``API.md``）。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from secrets import token_hex
+from typing import Any, Dict, List, Optional
+
+try:
+    import requests
+except ImportError as exc:  # pragma: no cover
+    raise ImportError("pcs SDK 需要 requests：pip install requests") from exc
+
+
+class PcsApiError(Exception):
+    """API 调用失败（HTTP 错误或非 success 响应）。"""
+
+    def __init__(
+        self,
+        message: str,
+        code: Optional[str] = None,
+        status_code: Optional[int] = None,
+    ) -> None:
+        """构造 API 错误。
+
+        :param message: 错误描述
+        :param code: 业务错误码（如 ``PARAM_ERROR`` / ``INSUFFICIENT_BALANCE``），可选
+        :param status_code: HTTP 状态码，可选
+        """
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+
+    def __str__(self) -> str:
+        if self.code:
+            return "[{}] {}".format(self.code, self.message)
+        return self.message
+
+
+class PcsClient:
+    """pcs HTTP API 客户端（费用模块 + 防火墙模块）。"""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        timeout: float = 10.0,
+        session: Optional["requests.Session"] = None,
+    ) -> None:
+        """
+        :param base_url: API 根地址，如 ``https://pcs.example.com``
+        :param api_key: 与服务端 ``API_KEY`` 一致的密钥（仅本地签名用，不随请求传输）
+        :param timeout: 请求超时（秒）
+        :param session: 可复用的 ``requests.Session``；缺省自动创建
+        """
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._timeout = timeout
+        self._session = session or requests.Session()
+
+    # -- 签名与底层请求 ----------------------------------------------------
+    def _auth_headers(self) -> Dict[str, str]:
+        # 每次请求都重新生成时间戳与随机 nonce，保证签名不可重放
+        ts = str(int(time.time()))
+        nonce = token_hex(8)
+        # 待签名字符串 = 时间戳与 nonce 直接拼接（如 "1700000000a1b2c3d4"），
+        # 用 api_key 做 HMAC-SHA256 得到十六进制签名值
+        sign = hmac.new(
+            self._api_key.encode("utf-8"),
+            (ts + nonce).encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+        return {
+            "X-Timestamp": ts,
+            "X-Nonce": nonce,
+            "X-Signature": sign,
+            "Accept": "application/json",
+        }
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """发起一次签名鉴权的 HTTP 请求并统一解析业务响应。
+
+        :param method: HTTP 方法（``GET`` / ``POST`` ...）
+        :param path: 接口路径，如 ``/api/fee/balance``
+        :param params: 查询参数（GET）
+        :param json: 请求体（POST），以 JSON 序列化
+        :return: 业务成功时返回响应体中的 ``data`` 字段
+        :rtype: Any
+        :raises PcsApiError: HTTP 错误（>= 400）或业务层 ``success is False`` 时抛出
+        """
+        resp = self._session.request(
+            method,
+            self._base_url + path,
+            params=params,
+            json=json,
+            headers=self._auth_headers(),
+            timeout=self._timeout,
+        )
+        # 统一解析 JSON：非 JSON 且为错误状态码时直接以原始文本报错
+        try:
+            body = resp.json()
+        except ValueError:
+            if resp.status_code >= 400:
+                raise PcsApiError(
+                    resp.text or "HTTP {}".format(resp.status_code),
+                    status_code=resp.status_code,
+                ) from None
+            raise PcsApiError("invalid json response") from None
+        # 业务层约定：HTTP >= 400 或 body.success is False 都视为失败
+        if resp.status_code >= 400 or body.get("success") is False:
+            raise PcsApiError(
+                body.get("message") or "request failed",
+                code=body.get("code"),
+                status_code=resp.status_code,
+            )
+        return body.get("data")
+
+    # -- 费用模块 ----------------------------------------------------------
+    def fee_balance(
+        self, uid: str, module: str
+    ) -> Optional[Dict[str, Any]]:
+        """查询某个用户的指定模块费用状态（余额 / 生效 / 到期 / 档位）。
+
+        :param uid: 用户唯一标识
+        :param module: 付费模块标识
+        :return: 费用状态对象（dict）；记录不存在时返回 ``None``
+        :rtype: Optional[Dict[str, Any]]
+        """
+        return self._request(
+            "GET", "/api/fee/balance",
+            params={"uid": uid, "module": module},
+        )
+
+    def fee_balances(
+        self,
+        uid: str,
+        module: Optional[str] = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """查询用户全部模块的费用状态（按 ctime 倒序）。
+
+        :param uid: 用户唯一标识
+        :param module: 付费模块标识过滤，为空返回全部模块
+        :param limit: 返回条数上限
+        :param offset: 偏移量，配合 ``limit`` 分页
+        :return: 费用状态对象列表
+        :rtype: List[Dict[str, Any]]
+        """
+        params: Dict[str, Any] = {
+            "uid": uid, "limit": limit, "offset": offset,
+        }
+        if module:
+            params["module"] = module
+        return self._request("GET", "/api/fee/balances", params=params)
+
+    def fee_logs(
+        self,
+        uid: str,
+        module: Optional[str] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """查询费用流水（充值 / 消费记录）。
+
+        :param uid: 用户唯一标识
+        :param module: 付费模块标识过滤，为空返回全部模块
+        :param limit: 返回条数上限
+        :param offset: 偏移量，配合 ``limit`` 分页
+        :return: 流水记录列表
+        :rtype: List[Dict[str, Any]]
+        """
+        params: Dict[str, Any] = {
+            "uid": uid, "limit": limit, "offset": offset,
+        }
+        if module:
+            params["module"] = module
+        return self._request("GET", "/api/fee/logs", params=params)
+
+    def fee_modules(
+        self, module: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """查询已登记的付费模块（含支持的付费类型、档位与档位费用）。
+
+        :param module: 模块标识过滤，为空返回全部
+        :return: 付费模块元数据列表
+        :rtype: List[Dict[str, Any]]
+        """
+        params = {"module": module} if module else None
+        return self._request("GET", "/api/fee/modules", params=params)
+
+    def fee_recharge(
+        self,
+        uid: str,
+        module: str,
+        amount: float,
+        *,
+        biz_no: str,
+        pay_type: str = "postpaid",
+        pay_source: str = "other",
+        level: str = "",
+        start_at: int = 0,
+        end_at: int = 0,
+        trade_no: str = "",
+        remark: str = "",
+        operator: str = "",
+    ) -> Dict[str, Any]:
+        """充值 / 续期（同一事务内更新费用状态并写流水）。
+
+        :param uid: 用户唯一标识
+        :param module: 付费模块标识
+        :param amount: 金额（元，保留两位小数）
+        :param biz_no: 幂等键，重试须复用原值，新动作须换新值
+        :param pay_type: 付费类型 ``prepaid`` / ``postpaid`` / ``lifetime``
+        :param pay_source: 付费来源 ``cash`` / ``alipay`` / ``wechat`` / ``qq`` / ``other``
+        :param level: 付费档位（仅 ``prepaid`` / ``lifetime`` 有意义，可空）
+        :param start_at: 生效时间（10 位时间戳）；``lifetime`` 忽略，``postpaid`` 仅首次入账时写
+        :param end_at: 结束时间（10 位时间戳）；仅 ``prepaid`` 可填，须晚于当前结束时间
+        :param trade_no: 交易号（可选）
+        :param remark: 备注（可选）
+        :param operator: 操作人（可选，仅服务端可传）
+        :return: 变更结果（含 ``duplicated`` 等字段）
+        :rtype: Dict[str, Any]
+        """
+        return self._request("POST", "/api/fee/recharge", json={
+            "uid": uid, "module": module, "amount": amount,
+            "pay_type": pay_type, "pay_source": pay_source, "level": level,
+            "start_at": start_at, "end_at": end_at, "biz_no": biz_no,
+            "trade_no": trade_no, "remark": remark, "operator": operator,
+        })
+
+    def fee_consume(
+        self,
+        uid: str,
+        module: str,
+        amount: float,
+        *,
+        biz_no: str,
+        remark: str = "",
+        operator: str = "",
+    ) -> Dict[str, Any]:
+        """消费扣减（仅按量付费 ``postpaid`` 模块，扣减 ``balance``）。
+
+        :param uid: 用户唯一标识
+        :param module: 付费模块标识
+        :param amount: 扣减金额（元，须 ≤ 当前余额）
+        :param biz_no: 幂等键，重试须复用原值，新动作须换新值
+        :param remark: 备注（可选）
+        :param operator: 操作人（可选，仅服务端可传）
+        :return: 扣减结果（含扣减后余额等字段）
+        :rtype: Dict[str, Any]
+        """
+        return self._request("POST", "/api/fee/consume", json={
+            "uid": uid, "module": module, "amount": amount,
+            "biz_no": biz_no, "remark": remark, "operator": operator,
+        })
+
+    # -- 主机管理 ----------------------------------------------------------
+    def host_hosts(self) -> List[Dict[str, Any]]:
+        """列出已登记主机（不含密码 / 私钥等敏感字段）。
+
+        :return: 主机列表
+        :rtype: List[Dict[str, Any]]
+        """
+        return self._request("GET", "/api/host/hosts")
+
+    # -- 防火墙临时放行 ----------------------------------------------------
+    def host_allows(
+        self,
+        host_id: Optional[int] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """列出防火墙临时放行记录。
+
+        :param host_id: 按主机过滤，为空返回全部主机
+        :param limit: 返回条数上限（封顶 200）
+        :param offset: 偏移量，配合 ``limit`` 分页
+        :return: 临时放行记录列表
+        :rtype: List[Dict[str, Any]]
+        """
+        params: Dict[str, Any] = {"limit": limit, "offset": offset}
+        if host_id is not None:
+            params["host_id"] = host_id
+        return self._request("GET", "/api/host/allows", params=params)
+
+    def host_allow(
+        self,
+        host_id: int,
+        ip: str,
+        port: str,
+        *,
+        protocol: str = "tcp",
+        expire_at: int = 0,
+        remark: str = "",
+    ) -> Dict[str, Any]:
+        """防火墙临时放行：允许 ``ip`` 访问指定主机的 ``protocol/port``，到期自动撤销。
+
+        :param host_id: 目标主机 ID（来自 ``host_hosts``）
+        :param ip: 来源 IP
+        :param port: 端口（单个 / 范围 / 多个不连续，逗号分隔）
+        :param protocol: 协议，``tcp`` 或 ``udp``
+        :param expire_at: 到期时间（10 位时间戳），``0`` 或缺省表示**永久**（不自动撤销）
+        :param remark: 备注（可选）
+        :return: 新建的放行记录
+        :rtype: Dict[str, Any]
+        """
+        return self._request("POST", "/api/host/allow", json={
+            "host_id": host_id, "ip": ip, "protocol": protocol,
+            "port": port, "expire_at": expire_at, "remark": remark,
+        })
+
+    def host_revoke(self, allow_id: int) -> Dict[str, Any]:
+        """撤销一条防火墙放行（幂等：不存在或已撤销即视为成功）。
+
+        :param allow_id: 放行记录 ID（来自 ``host_allows``）
+        :return: 撤销结果
+        :rtype: Dict[str, Any]
+        """
+        return self._request("POST", "/api/host/revoke", json={"id": allow_id})
+
+    # -- nginx 白名单 ------------------------------------------------------
+    def host_nginx_allows(
+        self,
+        host_id: Optional[int] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """列出 nginx 白名单记录。
+
+        :param host_id: 按主机过滤，为空返回全部主机
+        :param limit: 返回条数上限（封顶 200）
+        :param offset: 偏移量，配合 ``limit`` 分页
+        :return: 白名单记录列表
+        :rtype: List[Dict[str, Any]]
+        """
+        params: Dict[str, Any] = {"limit": limit, "offset": offset}
+        if host_id is not None:
+            params["host_id"] = host_id
+        return self._request("GET", "/api/host/nginx-allows", params=params)
+
+    def host_nginx_allow(
+        self,
+        host_id: int,
+        ip: str,
+        *,
+        expire_at: int = 0,
+        remark: str = "",
+    ) -> Dict[str, Any]:
+        """nginx 白名单：允许 ``ip`` 访问指定主机，到期自动撤销（pcs 全权托管 conf）。
+
+        :param host_id: 目标主机 ID（来自 ``host_hosts``）
+        :param ip: 来源 IP
+        :param expire_at: 到期时间（10 位时间戳），``0`` 或缺省表示**永久**（不自动撤销）
+        :param remark: 备注（可选）
+        :return: 新建的白名单记录
+        :rtype: Dict[str, Any]
+        """
+        return self._request("POST", "/api/host/nginx-allow", json={
+            "host_id": host_id, "ip": ip,
+            "expire_at": expire_at, "remark": remark,
+        })
+
+    def host_nginx_revoke(self, allow_id: int) -> Dict[str, Any]:
+        """撤销一条 nginx 白名单（幂等：不存在或已撤销即视为成功）。
+
+        :param allow_id: 白名单记录 ID（来自 ``host_nginx_allows``）
+        :return: 撤销结果
+        :rtype: Dict[str, Any]
+        """
+        return self._request(
+            "POST", "/api/host/nginx-revoke", json={"id": allow_id}
+        )

pcs_sdk-0.1.0/pcs_sdk.egg-info/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: pcs-sdk
+Version: 0.1.0
+Summary: pcs API client built on requests
+Author: staugur
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.20
+
+# pcs SDK
+
+pcs 的 Python 客户端，基于 `requests` 封装「费用模块」与「防火墙模块」接口，
+统一处理 HMAC-SHA256 请求签名、JSON 序列化与错误判定。接口字段与错误码见仓库根目录 `API.md`。
+
+## 安装
+
+```bash
+# 方式一：从 PyPI 安装（推荐）
+pip install pcs-sdk
+
+# 方式二：本地开发（可编辑安装）
+cd sdk
+pip install -e .
+
+# 方式三：直接安装 GitHub 仓库中的 sdk 子目录
+pip install "git+https://github.com/staugur/pcs.git#subdirectory=sdk"
+```
+
+## 版本号与发布
+
+版本号由 `setuptools_scm` 从 git 自动派生，**无需手改** `pcs/__init__.py` 里的
+`__version__`：
+
+- 打了 `v*` tag（如 `v0.1.0`）并推送 → 正式版 `0.1.0`；
+- 推送改动落到 `sdk/` 目录（仅 `master` / `dev` 分支）→ 自动发布开发版，版本号形如
+  `0.1.0.dev12+gabcdef`（距最近 tag 的提交数 + commit sha，天然唯一、不撞车）；
+- 在 Actions 页手动 Run workflow → 开发版 `0.1.0.dev<时间戳>`（精确到秒，天然唯一、
+  可直发 PyPI）。
+
+> 仅 `sdk/` 目录的改动会触发自动发布；改 `src/`、`AGENTS.md`、`API.md` 等其他目录
+> 不会触发，避免无关改动误发版本。同一 push 若同时命中多个触发条件（如打了 `v*` tag
+> 且其提交刚好改了 `sdk/`），工作流只运行一次。
+
+发布由仓库的 GitHub Action（`.github/workflows/publish.yml`）完成：
+
+- 推送 `v*` tag → 自动发布正式版到 PyPI；
+- 推送改动落到 `sdk/**`（仅 `master` / `dev`）→ 自动发布开发版；
+- 在 Actions 页手动 Run workflow → 快速发布开发版（无需打 tag）。
+
+> 采用 OIDC trusted publishing（免密钥）：首次发布前需在 PyPI 的 `pcs-sdk` 项目配置
+> Trusted Publisher（Owner=`staugur`、Repository name=`pcs`、Workflow name=`publish.yml`、
+> Environment name 留空），无需配置 `PYPI_API_TOKEN`。
+
+## 快速上手
+
+```python
+from pcs import PcsClient
+
+client = PcsClient("https://pcs.example.com", api_key="<API_KEY>")
+
+# 费用：查询余额（记录不存在返回 None）
+balance = client.fee_balance(uid="u1", module="blog")
+
+# 费用：查询全部模块状态 / 流水 / 付费模块
+client.fee_balances(uid="u1")
+client.fee_logs(uid="u1", module="blog", limit=50)
+client.fee_modules()
+
+# 费用：充值（biz_no 务必幂等——重试复用原值，新动作换新值）
+client.fee_recharge(
+    uid="u1", module="blog", amount=120, pay_type="prepaid",
+    pay_source="alipay", start_at=1790304000, end_at=1821840000,
+    level="pro", trade_no="202609010001",
+    biz_no="blog-2026-09-recharge-001",
+)
+
+# 费用：消费扣减（仅按量付费模块）
+client.fee_consume(uid="u1", module="blog", amount=30,
+                   biz_no="blog-2026-09-usage-001")
+
+# 主机管理：列出已登记主机
+client.host_hosts()
+
+# 防火墙：列出放行记录（按主机过滤 / 分页：limit 上限 200）
+client.host_allows(host_id=1)
+client.host_allows(limit=20, offset=0)
+
+# 防火墙：临时放行（到期时间 expire_at 为 10 位时间戳）
+client.host_allow(host_id=1, ip="1.2.3.4", port="3306",
+                  expire_at=1790304000 + 3600, remark="临时开库")
+
+# 防火墙：撤销放行
+client.host_revoke(allow_id=42)
+
+# nginx 白名单：列出 / 新增 / 撤销（pcs 全权托管 conf，到期自动 reload）
+client.host_nginx_allows(host_id=1)
+client.host_nginx_allow(host_id=1, ip="1.2.3.4",
+                        expire_at=1790304000 + 3600, remark="临时开站")
+client.host_nginx_revoke(allow_id=42)
+```
+
+## 错误处理
+
+接口返回 `success=false` 或 HTTP 错误时抛出 `pcs.PcsApiError`，可读取
+`code`（错误码，如 `PARAM_ERROR` / `INSUFFICIENT_BALANCE` / `IDEMPOTENCY_CONFLICT`）、
+`message` 与 `status_code`：
+
+```python
+from pcs import PcsClient, PcsApiError
+
+try:
+    client.fee_consume(uid="u1", module="blog", amount=999, biz_no="x-1")
+except PcsApiError as e:
+    print(e.code, e.status_code, e.message)
+```
+
+## 复用连接
+
+`PcsClient` 默认内部持有 `requests.Session`（连接池复用）。需要自定义会话
+（代理、证书、重试策略）时传入 `session=` 即可。

pcs_sdk-0.1.0/pcs_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+pcs/__init__.py
+pcs/client.py
+pcs_sdk.egg-info/PKG-INFO
+pcs_sdk.egg-info/SOURCES.txt
+pcs_sdk.egg-info/dependency_links.txt
+pcs_sdk.egg-info/requires.txt
+pcs_sdk.egg-info/scm_file_list.json
+pcs_sdk.egg-info/top_level.txt

pcs_sdk-0.1.0/pcs_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pcs_sdk-0.1.0/pcs_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.20

pcs_sdk-0.1.0/pcs_sdk.egg-info/scm_file_list.json

@@ -0,0 +1,8 @@
+{
+  "files": [
+    "README.md",
+    "pcs/__init__.py",
+    "pcs/client.py",
+    "pyproject.toml"
+  ]
+}

pcs_sdk-0.1.0/pcs_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+pcs

pcs_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61", "setuptools_scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pcs-sdk"
+dynamic = ["version"]
+description = "pcs API client built on requests"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = ["requests>=2.20"]
+authors = [{ name = "staugur" }]
+
+[tool.setuptools]
+packages = ["pcs"]
+
+# 版本号由 git 自动派生（无需手改 __version__）：
+# - 打了 v* tag（如 v0.1.0）→ 正式版 0.1.0
+# - 开发期手动快速发（workflow_dispatch）→ 0.1.0.dev<日期>（如 0.1.0.dev20261005，
+#   日期取自 UTC，天然唯一、可直发 PyPI；PyPI 要求 PEP 440，故用 .dev 前缀而非连字符）
+# - local_scheme=no-local-version 去掉 +g<sha> 本地后缀（PyPI 会拒收本地版本）
+[tool.setuptools_scm]
+version_scheme = "guess-next-dev"
+local_scheme = "no-local-version"
+fallback_version = "0.1.0"

pcs_sdk-0.1.0/setup.cfg

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