AboveColin/fitdays

# fitdays 一个非官方的 **async Python client**，用于访问 Fitdays (ICOMON) 智能体脂秤云 API。 Fitdays 是一系列白牌体脂秤背后的应用程序——包括 **Robi S6** 以及大量换标的同系列设备。体脂秤负责测量生物阻抗， 云端将其换算为脂肪 / 肌肉 / 水分 / 骨量 / BMR 等数据，而应用程序是 查看这些数据的唯一途径。由于没有公开的 API，因此该软件包直接对接了 应用程序的专属协议。 只读模式：它仅负责登录并拉取测量历史记录。绝不会向您的账户写入任何数据。 ``` pip install fitdays ``` ## 快速开始 ``` import asyncio from fitdays import FitdaysClient async def main(): async with await FitdaysClient.login("you@example.com", "hunter2") as client: latest = await client.get_latest() print(latest.weight_kg, "kg") print(latest.body_fat_pct, "% fat →", latest.body_fat_kg, "kg") print(latest.muscle_mass_kg, "kg muscle") asyncio.run(main()) ``` 查看 [`examples/quickstart.py`](examples/quickstart.py) 获取更完整的示例。 ## 您能获得什么 `get_sync()` 会在一次请求中返回所有数据： | | | |---|---| | `.measurements` | `Measurement` 对象，按最新时间优先排序 | | `.profiles` | 账户上的成员资料 (`UserProfile`) | | `.devices` | 绑定到该账户的体脂秤 (`ScaleDevice`) | 一个 `Measurement` 包含了体脂秤报告的所有数据 —— `weight_kg`、`bmi`、 `body_fat_pct`、`subcutaneous_fat_pct`、`visceral_fat`、`muscle_pct`、 `skeletal_muscle_pct`、`bone_mass_kg`、`body_water_pct`、`protein_pct`、`bmr`、 `body_age`、`heart_rate`、`impedance` —— 以及 API 仅以比例形式发送的推导质量数据：`body_fat_kg`、`muscle_mass_kg`、`skeletal_muscle_kg`、`body_water_kg`、 `protein_kg`。 `is_weight_only` 会告知您该次称重是否没有包含阻抗数据（比如穿着袜子，或者只是 匆匆站了一下体脂秤），这样您就可以跳过身体成分相关字段，而不必在图表中 显示空值。 ## 多用户 一个 Fitdays 账户可以保存多个成员资料，每个资料都有各自的 `suid`， 并且体脂秤会将每次称重结果归因于其中一个资料： ``` result = await client.get_sync() for profile in result.profiles: latest = result.latest(profile.suid) print(profile.display_name, latest.weight_kg) ``` ## 会话与 token 每次都进行登录不仅没有必要，而且对服务器也不友好。请换用持久化的会话： ``` stored = client.session.to_dict() # no plaintext password in here ... client = FitdaysClient.from_session(stored, token_updated=save_it) ``` 有两件事会自动发生： * **自愈式登录。** Token 的有效期很长，但并非永久。当某个 token 被拒绝时，客户端会使用已存储的密码 *digest* 重新进行身份验证 并重试请求——随后触发您的 `token_updated` 回调，以便您 持久化保存新的 token。 * **区域重定向。** 在欧洲以外地区注册的账户会返回 `code 302` 以及其真实所在的主机地址。客户端会自动跳转一次并 记住该地址。 ### 关于密码 登录端点需要 `MD5(MD5(password + "hx"))`，因此明文密码永远不会 离开您的进程 —— `Session` 仅存储该 digest，并且重新登录也仅 依赖该 digest 即可完成。但这仍然是一项凭证（对于此 API 而言，它等同于密码本身），因此请像存储 token 一样妥善存储它。 ## Home Assistant 这里有一个配套的集成组件：**[HA-Fitdays](https://github.com/AboveColin/HA-Fitdays)**， 它可以将每个成员资料转换为一个配备体脂传感器的设备。 ## 错误 | 异常 | 含义 | |---|---| | `FitdaysAuthError` | 登录失败，或者 token 已失效且无法续期 | | `FitdaysNetworkError` | 超时 / 连接问题 | | `FitdaysAPIError` | 云端返回了非成功的 `code` | | `FitdaysValidationError` | 您传入了无法处理的数据 | 所有异常均继承自 `FitdaysError`。 ## 免责声明 本软件与 GUANGDONG ICOMON 或 Fitdays 没有任何关联、认可或受到其支持。该 协议是通过观察应用程序针对作者本人账户的网络流量确定的。端点 可能会在不另行通知的情况下发生变更或失效。使用风险需自行承担。 ## 许可证 MIT —— 请参阅 [LICENSE](LICENSE)。

标签：API客户端, Python, 健康数据, 异步编程, 无后门, 智能体脂秤, 物联网, 计算机取证, 逆向工具