Metadata-Version: 2.4
Name: openhub-fee-sdk
Version: 0.1.0
Summary: openhub 费用接口 Python 客户端（/api/fee），基于 requests 封装 HMAC-SHA256 签名
Author: staugur
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.20

# openhub-fee-sdk

openhub 费用接口的 Python 客户端，基于 `requests` 封装 `/api/fee` 的全部接口，
统一处理 HMAC-SHA256 请求签名、JSON 序列化与错误判定。鉴权、字段与错误码见仓库
根目录 `arch/fee.md` 第 5 节。

> 注意：与 pcs 的费用接口不同，openhub **不开放直接入账**（`recharge`），资金只能经
> 管理员审核进入账本；SDK 因此不提供 `recharge`，转而提供**半自动收款**的订单类接口
> （建单 / 上传凭证 / 查单 / 取消）。

## 安装

```bash
# 方式一：从 PyPI 安装（推荐）
pip install openhub-fee-sdk

# 方式二：本地开发（可编辑安装）
cd sdk/fee
pip install -e .

# 方式三：直接安装 GitHub 仓库中的 sdk/fee 子目录
pip install "git+https://github.com/staugur/open-hub.git#subdirectory=sdk/fee"
```

## 版本号与发布

版本号由 `setuptools_scm` 从 git 自动派生，**无需手改** `openhub_fee/__init__.py` 里的
`__version__`：

- 打了 `v*` tag（如 `v0.1.0`）并推送 → 正式版 `0.1.0`；
- 推送改动落到 `sdk/fee/` 目录（仅 `master` / `dev` 分支）→ 自动发布开发版；
- 在 Actions 页手动 Run workflow → 开发版 `0.1.0.dev<时间戳>`（精确到秒，天然唯一、
  可直发 PyPI）。

> 仅 `sdk/fee/` 目录的改动会触发自动发布；改 `src/`、`arch/`、`README.md`
> 等其他目录（含 `sdk/` 下的其他项目，如 `sdk/ipamcli`）不会触发，避免无关改动误发版本。

发布由仓库的 GitHub Action（`.github/workflows/publish-sdk.yml`）完成：

- 推送 `v*` tag → 自动发布正式版到 PyPI；
- 推送改动落到 `sdk/fee/**`（仅 `master` / `dev`）→ 自动发布开发版；
- 在 Actions 页手动 Run workflow → 快速发布开发版（无需打 tag）。

> 采用 OIDC trusted publishing（免密钥）：首次发布前需在 PyPI 的 `openhub-fee-sdk`
> 项目配置 Trusted Publisher（Owner=`staugur`、Repository name=`open-hub`、
> Workflow name=`publish-sdk.yml`、Environment name 留空），无需配置 `PYPI_API_TOKEN`。

## 快速上手

```python
from openhub_fee import FeeClient

client = FeeClient("https://openhub.example.com", app_id="<APP_ID>", secret="<SECRET>")

# 费用：查询余额（记录不存在返回 None）
balance = client.fee_balance(uid="u1", module="sec")

# 费用：查询全部模块状态 / 流水 / 付费模块
client.fee_balances(uid="u1")
client.fee_logs(uid="u1", module="sec", limit=50)
client.fee_modules()

# 费用：按量扣费（仅 postpaid；biz_no 务必幂等——重试复用原值，新动作换新值）
client.fee_consume(uid="u1", module="sec", amount=30, biz_no="sec-usage-001")

# 半自动收款：建单 -> 上传凭证 -> 查单 / 取消
order = client.fee_order_create(uid="u1", module="sec", pay_type="prepaid", level="pro")
client.fee_order_upload_voucher(order["order_no"], "transfer.png")
client.fee_order_get(order["order_no"])
client.fee_order_cancel(order["order_no"])
```

## 错误处理

接口返回 `success=false` 或 HTTP 错误时抛出 `openhub_fee.FeeApiError`，可读取
`message` 与 `status_code`：

```python
from openhub_fee import FeeClient, FeeApiError

try:
    client.fee_consume(uid="u1", module="sec", amount=999, biz_no="x-1")
except FeeApiError as e:
    print(e.status_code, e.message)
```

> openhub 的业务错误响应目前不含 `code` 字段，故 `FeeApiError.code` 恒为 `None`。

## 复用连接

`FeeClient` 默认内部持有 `requests.Session`（连接池复用）。需要自定义会话
（代理、证书、重试策略）时传入 `session=` 即可。
